@runtime-type-inspector/transpiler 5.0.0 → 5.0.2

package/index.mjs

@@ -161,6 +161,8 @@ function toSourceTS(node) {
     // parseType("string"                         ).kind                 === ts.SyntaxKind.StringKeyword
     StringLiteral,
     // parseType("'test'"                         ).literal.kind         === ts.SyntaxKind.StringLiteral
+    SymbolKeyword,
+    // parseType("symbol"                         ).kind                 === ts.SyntaxKind.SymbolKeyword
     ThisType,
     // parseType("this"                           ).kind                 === ts.SyntaxKind.ThisType
     TupleType,
@@ -212,7 +214,11 @@ function toSourceTS(node) {
     NamedTupleMember,
     // parseType('[a: 1]'                         ).elements[0].kind     === ts.SyntaxKind.NamedTupleMember
     MappedType,
-    // parseType('{[K in TaskType]: 123}'         ).kind                 === ts.SyntaxKind.MappedType
+    // parseType('{[K in TaskType]: 123}'         ).kind                 ===  ts.SyntaxKind.MappedType
+    MinusToken,
+    // parseType('{[K in TaskType]-?: 123}'        ).questionToken.kind  === ts.SyntaxKind.MinusToken
+    PlusToken,
+    // parseType('{[K in TaskType]+?: 123}'        ).questionToken.kind  === ts.SyntaxKind.PlusToken
     TypeParameter,
     // parseType('{[K in TaskType]: 123}'         ).typeParameter.kind   ===  ts.SyntaxKind.TypeParameter
     QualifiedName,
@@ -329,12 +335,26 @@ function toSourceTS(node) {
           // For example: {[K in TaskType]: InstanceType etc.
           const iterable = toSourceTS(parameter.constraint); // TaskType
           const element = toSourceTS(parameter.name); // K
-          return {
+          const out = {
             type: 'mapping',
             iterable,
             element,
             result
           };
+          if (node.nameType) {
+            // `as` key remapping, e.g. {[K in keyof T as K extends string ? K : never]: ...}
+            out.nameType = toSourceTS(node.nameType);
+          }
+          // Modifiers: `-?` strips optionality, `+?`/`?` force it;
+          // `-readonly` strips readonly, `+readonly`/`readonly` force it.
+          // Absent modifiers preserve the source behavior (see createTypeFromMapping).
+          if (node.questionToken) {
+            out.question = node.questionToken.kind === MinusToken ? '-' : node.questionToken.kind === PlusToken ? '+' : '?';
+          }
+          if (node.readonlyToken) {
+            out.readonly = node.readonlyToken.kind === MinusToken ? '-' : node.readonlyToken.kind === PlusToken ? '+' : 'readonly';
+          }
+          return out;
         }
         console.warn("MappedType: expected TypeParameter");
         return 'transpiler-error';
@@ -552,6 +572,13 @@ function toSourceTS(node) {
                 optional: true
               };
             }
+            if (Array.isArray(member.modifiers) && member.modifiers.some(modifier => modifier.kind === ReadonlyKeyword)) {
+              // Tracked for IfEquals-style comparisons; ignored by validation.
+              if (type && typeof type === 'object') type.readonly = true;else type = {
+                type,
+                readonly: true
+              };
+            }
             properties[name] = type;
           } else {
             console.warn('TypeLiteral: unhandled member', member);
@@ -611,6 +638,7 @@ function toSourceTS(node) {
     case AnyKeyword:
     case BooleanKeyword:
     case StringKeyword:
+    case SymbolKeyword:
     case NeverKeyword:
     case NullKeyword:
     case NumberKeyword:
@@ -691,6 +719,7 @@ function toSourceTS(node) {
  */
 /**
  * Splits a string by a delimiter, ignoring delimiters nested inside <>, {}, [], ().
+ * Quote-aware: delimiters inside '...', "..." or `...` never split.
  * @param {string} str - The string to split.
  * @param {string} delimiter - Single character delimiter.
  * @returns {string[]} Top-level split parts.
@@ -701,10 +730,19 @@ function splitTopLevel(str, delimiter) {
   let depthCurly = 0;
   let depthSquare = 0;
   let depthParen = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inBacktick = false;
   let current = '';
-  for (const c of str) {
-    if (c === '<') depthAngle++;else if (c === '>') depthAngle--;else if (c === '{') depthCurly++;else if (c === '}') depthCurly--;else if (c === '[') depthSquare++;else if (c === ']') depthSquare--;else if (c === '(') depthParen++;else if (c === ')') depthParen--;
-    if (c === delimiter && depthAngle === 0 && depthCurly === 0 && depthSquare === 0 && depthParen === 0) {
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    const prev = i > 0 ? str[i - 1] : '';
+    if (c === "'" && !inDouble && !inBacktick && prev !== '\\') inSingle = !inSingle;else if (c === '"' && !inSingle && !inBacktick && prev !== '\\') inDouble = !inDouble;else if (c === '`' && !inSingle && !inDouble && prev !== '\\') inBacktick = !inBacktick;
+    const inQuote = inSingle || inDouble || inBacktick;
+    if (!inQuote) {
+      if (c === '<') depthAngle++;else if (c === '>') depthAngle--;else if (c === '{') depthCurly++;else if (c === '}') depthCurly--;else if (c === '[') depthSquare++;else if (c === ']') depthSquare--;else if (c === '(') depthParen++;else if (c === ')') depthParen--;
+    }
+    if (c === delimiter && !inQuote && depthAngle === 0 && depthCurly === 0 && depthSquare === 0 && depthParen === 0) {
       parts.push(current);
       current = '';
     } else {
@@ -714,6 +752,123 @@ function splitTopLevel(str, delimiter) {
   parts.push(current);
   return parts;
 }
+/**
+ * Depth state at a given index, quote-aware.
+ * @param {string} str - The string to scan.
+ * @param {number} upto - Exclusive end index.
+ * @returns {{angle: number, curly: number, square: number, paren: number, quote: boolean}} Depths.
+ */
+function depthsAt(str, upto) {
+  let angle = 0;
+  let curly = 0;
+  let square = 0;
+  let paren = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inBacktick = false;
+  for (let i = 0; i < upto; i++) {
+    const c = str[i];
+    const prev = i > 0 ? str[i - 1] : '';
+    if (c === "'" && !inDouble && !inBacktick && prev !== '\\') inSingle = !inSingle;else if (c === '"' && !inSingle && !inBacktick && prev !== '\\') inDouble = !inDouble;else if (c === '`' && !inSingle && !inDouble && prev !== '\\') inBacktick = !inBacktick;
+    const inQuote = inSingle || inDouble || inBacktick;
+    if (inQuote) continue;
+    if (c === '<') angle++;else if (c === '>') angle--;else if (c === '{') curly++;else if (c === '}') curly--;else if (c === '[') square++;else if (c === ']') square--;else if (c === '(') paren++;else if (c === ')') paren--;
+  }
+  return {
+    angle,
+    curly,
+    square,
+    paren,
+    quote: inSingle || inDouble || inBacktick
+  };
+}
+/**
+ * Finds a keyword (e.g. `in`, `as`, `extends`) at top level, outside brackets/quotes.
+ * @param {string} str - The string to search.
+ * @param {string} keyword - Keyword without surrounding spaces.
+ * @returns {number} Start index or -1.
+ */
+function findTopLevelKeyword(str, keyword) {
+  const isWord = c => /[A-Za-z0-9_$]/.test(c);
+  for (let i = 0; i <= str.length - keyword.length; i++) {
+    if (str.slice(i, i + keyword.length) !== keyword) continue;
+    const before = i > 0 ? str[i - 1] : ' ';
+    const after = i + keyword.length < str.length ? str[i + keyword.length] : ' ';
+    if (isWord(before) || isWord(after)) continue;
+    const d = depthsAt(str, i);
+    if (d.angle === 0 && d.curly === 0 && d.square === 0 && d.paren === 0 && !d.quote) {
+      // Ensure remainder after keyword is also top-level (keyword itself not quoted).
+      const d2 = depthsAt(str, i + keyword.length);
+      if (!d2.quote) return i;
+    }
+  }
+  return -1;
+}
+/**
+ * Finds a single-char delimiter at top level, outside brackets/quotes.
+ * @param {string} str - The string to search.
+ * @param {string} delimiter - Single character.
+ * @param {number} from - Start index.
+ * @returns {number} Index or -1.
+ */
+function findTopLevelChar(str, delimiter, from = 0) {
+  let angle = 0;
+  let curly = 0;
+  let square = 0;
+  let paren = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inBacktick = false;
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    // Check at depths *before* the current char, so `[` itself is findable.
+    const inQuoteBefore = inSingle || inDouble || inBacktick;
+    if (i >= from && c === delimiter && !inQuoteBefore && angle === 0 && curly === 0 && square === 0 && paren === 0) {
+      return i;
+    }
+    const prev = i > 0 ? str[i - 1] : '';
+    if (c === "'" && !inDouble && !inBacktick && prev !== '\\') inSingle = !inSingle;else if (c === '"' && !inSingle && !inBacktick && prev !== '\\') inDouble = !inDouble;else if (c === '`' && !inSingle && !inDouble && prev !== '\\') inBacktick = !inBacktick;
+    const inQuote = inSingle || inDouble || inBacktick;
+    if (!inQuote) {
+      if (c === '<') angle++;else if (c === '>') angle--;else if (c === '{') curly++;else if (c === '}') curly--;else if (c === '[') square++;else if (c === ']') square--;else if (c === '(') paren++;else if (c === ')') paren--;
+    }
+  }
+  return -1;
+}
+/**
+ * Strips balanced outer parens, e.g. `(( T ))` -> `T`.
+ * @param {string} type - Trimmed type string.
+ * @returns {string} Unwrapped type.
+ */
+function stripOuterParens(type) {
+  let changed = true;
+  while (changed) {
+    changed = false;
+    if (type.length >= 2 && type[0] === '(' && type[type.length - 1] === ')') {
+      let depth = 0;
+      let balanced = true;
+      let inSingle = false;
+      let inDouble = false;
+      for (let i = 0; i < type.length; i++) {
+        const c = type[i];
+        if (c === "'" && !inDouble && type[i - 1] !== '\\') inSingle = !inSingle;else if (c === '"' && !inSingle && type[i - 1] !== '\\') inDouble = !inDouble;else if (!inSingle && !inDouble) {
+          if (c === '(') depth++;else if (c === ')') {
+            depth--;
+            if (depth === 0 && i !== type.length - 1) {
+              balanced = false;
+              break;
+            }
+          }
+        }
+      }
+      if (balanced && depth === 0) {
+        type = type.slice(1, -1).trim();
+        changed = true;
+      }
+    }
+  }
+  return type;
+}
 /**
  * Parses `Name<A, B>` into name + raw arg strings, respecting nested brackets.
  * Returns undefined when input isn't a generic reference.
@@ -754,6 +909,190 @@ function parseGenericReference(type) {
     args
   };
 }
+/**
+ * Parses `{[K in Iterable as NameType]?: Result}` mapped syntax.
+ * Returns undefined when input isn't a mapped type.
+ * @param {string} type - Trimmed type string starting with `{`.
+ * @returns {object|undefined} Mapping struct with raw strings, or undefined.
+ */
+function parseMappedRaw(type) {
+  if (type[0] !== '{' || type[type.length - 1] !== '}') {
+    return;
+  }
+  let inner = type.slice(1, -1).trim();
+  let readonly;
+  if (inner.startsWith('-readonly') && (inner[9] === ' ' || inner[9] === '[')) {
+    readonly = '-';
+    inner = inner.slice(9).trim();
+  } else if (inner.startsWith('+readonly') && (inner[9] === ' ' || inner[9] === '[')) {
+    readonly = '+';
+    inner = inner.slice(9).trim();
+  } else if (inner.startsWith('readonly') && (inner[8] === ' ' || inner[8] === '[')) {
+    readonly = 'readonly';
+    inner = inner.slice(8).trim();
+  }
+  if (inner[0] !== '[') {
+    return;
+  }
+  // Find matching `]` for the opening `[`, quote-aware.
+  let square = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inBacktick = false;
+  let close = -1;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    const prev = i > 0 ? inner[i - 1] : '';
+    if (c === "'" && !inDouble && !inBacktick && prev !== '\\') inSingle = !inSingle;else if (c === '"' && !inSingle && !inBacktick && prev !== '\\') inDouble = !inDouble;else if (c === '`' && !inSingle && !inDouble && prev !== '\\') inBacktick = !inBacktick;else if (!inSingle && !inDouble && !inBacktick) {
+      if (c === '[') square++;else if (c === ']') {
+        square--;
+        if (square === 0) {
+          close = i;
+          break;
+        }
+      }
+    }
+  }
+  if (close === -1) {
+    return;
+  }
+  const bracket = inner.slice(1, close);
+  let rest = inner.slice(close + 1).trim();
+  let question;
+  if (rest.startsWith('-?')) {
+    question = '-';
+    rest = rest.slice(2).trim();
+  } else if (rest.startsWith('+?')) {
+    question = '+';
+    rest = rest.slice(2).trim();
+  } else if (rest.startsWith('?')) {
+    question = '?';
+    rest = rest.slice(1).trim();
+  }
+  if (!rest.startsWith(':')) {
+    return;
+  }
+  const resultRaw = rest.slice(1).trim();
+  if (!resultRaw) {
+    return;
+  }
+  const inIdx = findTopLevelKeyword(bracket, 'in');
+  if (inIdx === -1) {
+    return;
+  }
+  const element = bracket.slice(0, inIdx).trim();
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(element)) {
+    return;
+  }
+  const afterIn = bracket.slice(inIdx + 2).trim();
+  if (!afterIn) {
+    return;
+  }
+  const asIdx = findTopLevelKeyword(afterIn, 'as');
+  let iterableRaw = afterIn;
+  let nameRaw;
+  if (asIdx !== -1) {
+    iterableRaw = afterIn.slice(0, asIdx).trim();
+    nameRaw = afterIn.slice(asIdx + 2).trim();
+    if (!iterableRaw || !nameRaw) {
+      return;
+    }
+  }
+  return {
+    element,
+    iterableRaw,
+    nameRaw,
+    resultRaw,
+    question,
+    readonly
+  };
+}
+/**
+ * Splits `Check extends Extends ? True : False` at top level.
+ * Returns undefined when input isn't a conditional type.
+ * @param {string} type - Trimmed type string.
+ * @returns {{check: string, extends_: string, true_: string, false_: string}|undefined} Raw parts.
+ */
+function parseConditionRaw(type) {
+  const qIdx = findTopLevelChar(type, '?');
+  if (qIdx === -1) {
+    return;
+  }
+  const beforeQ = type.slice(0, qIdx);
+  const afterQ = type.slice(qIdx + 1);
+  const extIdx = findTopLevelKeyword(beforeQ, 'extends');
+  if (extIdx === -1) {
+    return;
+  }
+  const colonIdx = findTopLevelChar(afterQ, ':');
+  if (colonIdx === -1) {
+    return;
+  }
+  const check = beforeQ.slice(0, extIdx).trim();
+  const extends_ = beforeQ.slice(extIdx + 7).trim();
+  const true_ = afterQ.slice(0, colonIdx).trim();
+  const false_ = afterQ.slice(colonIdx + 1).trim();
+  if (!check || !extends_ || !true_ || !false_) {
+    return;
+  }
+  // Guard against `?.` optional chaining and `??` nullish coalescing.
+  if (type[qIdx + 1] === '.' || type[qIdx + 1] === '?') {
+    return;
+  }
+  return {
+    check,
+    extends_,
+    true_,
+    false_
+  };
+}
+/**
+ * Splits `Object[Index]` at top level. Excludes tuples (`[...]`) and
+ * empty-index arrays (`T[]`, handled earlier).
+ * @param {string} type - Trimmed type string.
+ * @returns {{objectRaw: string, indexRaw: string}|undefined} Raw parts.
+ */
+function parseIndexedAccessRaw(type) {
+  if (!type.endsWith(']') || type.endsWith('[]')) {
+    return;
+  }
+  if (type[0] === '[') {
+    return;
+  }
+  const openIdx = findTopLevelChar(type, '[');
+  if (openIdx === -1) {
+    return;
+  }
+  // Ensure the `[` at openIdx closes at the very end.
+  let square = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let inBacktick = false;
+  for (let i = openIdx; i < type.length; i++) {
+    const c = type[i];
+    const prev = i > 0 ? type[i - 1] : '';
+    if (c === "'" && !inDouble && !inBacktick && prev !== '\\') inSingle = !inSingle;else if (c === '"' && !inSingle && !inBacktick && prev !== '\\') inDouble = !inDouble;else if (c === '`' && !inSingle && !inDouble && prev !== '\\') inBacktick = !inBacktick;else if (!inSingle && !inDouble && !inBacktick) {
+      if (c === '[') square++;else if (c === ']') {
+        square--;
+        if (square === 0 && i !== type.length - 1) {
+          return;
+        }
+      }
+    }
+  }
+  if (square !== 0) {
+    return;
+  }
+  const objectRaw = type.slice(0, openIdx).trim();
+  const indexRaw = type.slice(openIdx + 1, -1).trim();
+  if (!objectRaw || !indexRaw) {
+    return;
+  }
+  return {
+    objectRaw,
+    indexRaw
+  };
+}
 /**
  * 'DepFree' refers to the fact that this function has no dependencies,
  * while `expandType` depends on TypeScript itself for maximum compatibility.
@@ -769,6 +1108,33 @@ function parseGenericReference(type) {
  */
 function expandTypeDepFree(type) {
   type = type.trim();
+  // '(123)' -> '123': strip balanced outer parens first so `(cond)?`
+  // nullable and `(A|B)` unions see through them.
+  const stripped = stripOuterParens(type);
+  if (stripped !== type) {
+    return expandTypeDepFree(stripped);
+  }
+  // `readonly T` erased at runtime, same shape as the inner type.
+  if (type.startsWith('readonly ') && type.length > 9) {
+    return expandTypeDepFree(type.slice(9).trim());
+  }
+  if (type === 'unique symbol') {
+    return 'any';
+  }
+  // Conditionals before nullable: `A extends B ? C : D?` must keep the
+  // nullable on the false branch, not lift it over the whole condition.
+  // (`(cond)?` has no top-level `?` due to parens, so it falls through
+  // to nullable below.)
+  const earlyCond = parseConditionRaw(type);
+  if (earlyCond) {
+    return {
+      type: 'condition',
+      checkType: expandTypeDepFree(earlyCond.check),
+      extendsType: expandTypeDepFree(earlyCond.extends_),
+      trueType: expandTypeDepFree(earlyCond.true_),
+      falseType: expandTypeDepFree(earlyCond.false_)
+    };
+  }
   // JSDocNullableType (`T?` / `?T`): union with null, matching expandType().
   if (type.endsWith('?') && type.length > 1) {
     return {
@@ -782,20 +1148,9 @@ function expandTypeDepFree(type) {
       members: [expandTypeDepFree(type.slice(1).trim()), 'null']
     };
   }
-  // `readonly T` erased at runtime, same shape as the inner type.
-  if (type.startsWith('readonly ') && type.length > 9) {
-    return expandTypeDepFree(type.slice(9).trim());
-  }
-  if (type === 'unique symbol') {
-    return 'any';
-  }
-  // '(123)' -> '123'
-  while (!type.includes('|') && type[0] === '(' && type[type.length - 1] === ')') {
-    type = type.slice(1, -1).trim();
-  }
   // (1) Rest parameters like ...string
   if (type[0] === '.' && type[1] === '.' && type[2] === '.') {
-    const elementType = type.slice(3);
+    const elementType = expandTypeDepFree(type.slice(3).trim());
     return {
       type: 'array',
       elementType
@@ -823,17 +1178,18 @@ function expandTypeDepFree(type) {
   // (3) Object<...> or Record<...>
   if ((type.startsWith("Object<") || type.startsWith("Record<")) && type.endsWith('>')) {
     const recordSlice = type.slice(7, -1);
-    const firstComma = recordSlice.indexOf(',');
-    if (firstComma === -1) {
+    const commaIdx = findTopLevelChar(recordSlice, ',');
+    if (commaIdx === -1) {
       console.warn("expandTypeDepFree> invalid Object/Record");
+    } else {
+      const key = recordSlice.slice(0, commaIdx).trim();
+      const val = recordSlice.slice(commaIdx + 1).trim();
+      return {
+        type: "record",
+        key: expandTypeDepFree(key),
+        val: expandTypeDepFree(val)
+      };
     }
-    const key = recordSlice.slice(0, firstComma).trim();
-    const val = recordSlice.slice(firstComma + 1).trim();
-    return {
-      type: "record",
-      key: expandTypeDepFree(key),
-      val: expandTypeDepFree(val)
-    };
   }
   // (3b) Map<...> / Set<...' for dep-free parity with expandType()
   if (type.startsWith("Map<") && type.endsWith('>')) {
@@ -868,33 +1224,89 @@ function expandTypeDepFree(type) {
       args: args.map(expandTypeDepFree)
     };
   }
-  // (4) {...}
+  // (4) Mapped types `{[K in X as Y]?: Z}` before the object-literal fallback.
   if (type[0] === '{' && type[type.length - 1] === '}') {
-    const propertiesArray = type.slice(1, -1).split(','); // ['entity: Entity', ' app: AppBase']
+    const mapped = parseMappedRaw(type);
+    if (mapped) {
+      const out = {
+        type: 'mapping',
+        iterable: expandTypeDepFree(mapped.iterableRaw),
+        element: mapped.element,
+        result: expandTypeDepFree(mapped.resultRaw)
+      };
+      if (mapped.nameRaw !== undefined) {
+        out.nameType = expandTypeDepFree(mapped.nameRaw);
+      }
+      if (mapped.question !== undefined) {
+        out.question = mapped.question;
+      }
+      if (mapped.readonly !== undefined) {
+        out.readonly = mapped.readonly;
+      }
+      return out;
+    }
+    const propertiesArray = splitTopLevel(type.slice(1, -1), ','); // ['entity: Entity', ' app: AppBase']
     const properties = {};
-    propertiesArray.forEach(_ => {
-      const [propName, propType] = _.split(":").map(_ => _.trim());
-      if (!propName || !propType) {
+    for (const entry of propertiesArray) {
+      const colonIdx = findTopLevelChar(entry, ':');
+      if (colonIdx === -1) {
+        // Empty `{}` yields one empty entry: the empty object type.
+        if (entry.trim() === '') {
+          continue;
+        }
         console.warn('expandTypeDepFree> unexpected type format, fix');
-        return false;
+        continue;
       }
-      properties[propName] = propType;
-    });
+      const propName = entry.slice(0, colonIdx).trim();
+      const propTypeRaw = entry.slice(colonIdx + 1).trim();
+      if (!propName || !propTypeRaw) {
+        console.warn('expandTypeDepFree> unexpected type format, fix');
+        continue;
+      }
+      properties[propName] = expandTypeDepFree(propTypeRaw);
+    }
     return {
       type: 'object',
       properties
     };
   }
-  // (5) expand unions
-  const members = type.split("|");
-  if (members.length >= 2) {
-    members.forEach((_, i) => members[i] = _.trim());
+  // (5) Unions and intersections via top-level splits (`&` binds tighter, so `|` first).
+  // Note: conditionals already handled up front (before nullable) so `D?`
+  // false branches keep their nullability; this slot is intentionally union-only.
+  const unionParts = splitTopLevel(type, "|");
+  if (unionParts.length >= 2) {
     return {
       type: 'union',
-      members: members.map(expandTypeDepFree)
+      members: unionParts.map(_ => expandTypeDepFree(_.trim()))
+    };
+  }
+  const interParts = splitTopLevel(type, "&");
+  if (interParts.length >= 2) {
+    return {
+      type: 'intersection',
+      members: interParts.map(_ => expandTypeDepFree(_.trim()))
+    };
+  }
+  // (7) `keyof T` before typeof so `keyof typeof X` nests correctly.
+  if (type.startsWith('keyof ') || type.startsWith('keyof(')) {
+    const after = type.startsWith('keyof(') ? type.slice(5).trim() : type.slice(6).trim();
+    if (after) {
+      return {
+        type: 'keyof',
+        argument: expandTypeDepFree(after)
+      };
+    }
+  }
+  // (8) Indexed access `T[K]` (arrays `T[]` handled below, tuples above start with `[`).
+  const indexed = parseIndexedAccessRaw(type);
+  if (indexed) {
+    return {
+      type: 'indexedAccess',
+      index: expandTypeDepFree(indexed.indexRaw),
+      object: expandTypeDepFree(indexed.objectRaw)
     };
   }
-  // (6) expand [] Arrays
+  // (9) expand [] Arrays
   // Test arrays: new pc.Mat3().set([1, 2, 3, "asd"])
   if (type.endsWith("[]")) {
     const typeSlice = type.slice(0, -2);
@@ -903,17 +1315,24 @@ function expandTypeDepFree(type) {
       elementType: expandTypeDepFree(typeSlice)
     };
   }
-  // (7) expand tuples
+  // (10) expand tuples
   if (type[0] === '[' && type[type.length - 1] === ']') {
-    const elements = type.slice(1, -1).split(','); // ['null', ' Texture', ' Texture', ' Texture', ' Texture', ' Texture', ' Texture']
+    const inner = type.slice(1, -1);
+    if (inner.trim() === '') {
+      return {
+        type: 'tuple',
+        elements: []
+      };
+    }
+    const elements = splitTopLevel(inner, ','); // ['null', ' Texture', ...]
     return {
       type: 'tuple',
-      elements: elements.map(expandTypeDepFree)
+      elements: elements.map(_ => expandTypeDepFree(_.trim()))
     };
   }
-  // (8) expand typeof expressions
+  // (11) expand typeof expressions
   if (type.startsWith('typeof ')) {
-    const argument = expandTypeDepFree(type.substring(7));
+    const argument = expandTypeDepFree(type.substring(7).trim());
     return {
       type: 'typeof',
       argument
@@ -939,81 +1358,19 @@ function expandTypeDepFree(type) {
   return type;
 }
 
-/**
- * Infers a parameter type from its default value AST node.
- * Returns widened types like TypeScript does (`= 0` means `number`, not
- * literal `0`; `= null` widens to `any`).
- * Returns `undefined` when nothing useful can be inferred — the caller then
- * emits no check, exactly like an undocumented parameter today.
- * Shapes match what `expandType` produces so they can be embedded as-is.
- * @param {import('@babel/types').Node} node - The default value AST node.
- * @returns {string | object | undefined} Inferred type or `undefined` to skip.
- */
-function inferTypeFromDefault$1(node) {
-  if (!node) {
-    return;
-  }
-  switch (node.type) {
-    case 'NumericLiteral':
-      return 'number';
-    case 'StringLiteral':
-      return 'string';
-    case 'BooleanLiteral':
-      return 'boolean';
-    case 'BigIntLiteral':
-      return {
-        type: 'bigint'
-      };
-    case 'RegExpLiteral':
-      return 'RegExp';
-    case 'TemplateLiteral':
-      return 'string';
-    case 'ArrayExpression':
-      return {
-        type: 'array',
-        elementType: 'any'
-      };
-    case 'ObjectExpression':
-      return {
-        type: 'object',
-        properties: {}
-      };
-    case 'ArrowFunctionExpression':
-    case 'FunctionExpression':
-      return 'Function';
-    case 'NewExpression':
-      {
-        const {
-          callee
-        } = node;
-        if (callee.type === 'Identifier') {
-          return callee.name;
-        }
-        break;
-      }
-    case 'UnaryExpression':
-      {
-        const {
-          operator,
-          argument
-        } = node;
-        if (operator === '!') {
-          return 'boolean';
-        }
-        if (operator === 'void' || operator === 'typeof') {
-          return operator === 'void' ? 'undefined' : 'string';
-        }
-        if ((operator === '-' || operator === '+') && argument.type === 'NumericLiteral') {
-          return 'number';
-        }
-        if ((operator === '-' || operator === '+') && argument.type === 'BigIntLiteral') {
-          return {
-            type: 'bigint'
-          };
+function _extends() {
+  _extends = Object.assign ? Object.assign.bind() : function (target) {
+    for (var i = 1; i < arguments.length; i++) {
+      var source = arguments[i];
+      for (var key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+          target[key] = source[key];
         }
-        break;
       }
-  }
+    }
+    return target;
+  };
+  return _extends.apply(this, arguments);
 }
 
 /**
@@ -1069,76 +1426,791 @@ function extractCurlyContent(line) {
       break;
     }
   }
-  const content = line.substring(firstCurly + 1, k);
+  const content = line.substring(firstCurly + 1, k);
+  return {
+    content,
+    nextIndex: k + 1
+  };
+}
+/**
+ * Parses JSDoc comments to extract and expand typedefs and their associated properties.
+ *
+ * It iterates through the lines of a `CommentBlock` from the Babel AST, looking for `@typedef` and `@property`
+ * annotations. When it finds a typedef, it stores it in the `typedefs` record. When it finds a property,
+ * it adds it to the last found typedef if it is an object type. `@template` names preceding a
+ * typedef are recorded in `typedefTemplates` so generic references can instantiate.
+ * @param {Record<string, object>} typedefs - An object to store typedefs, mapping type names to their expanded definitions.
+ * @param {Record<string, string[]>} typedefTemplates - An object to store template parameter names per generic typedef.
+ * @param {Console["warn"]} warn - A warn function used for emitting warnings about non-extensible types.
+ * @param {import("@babel/types").Comment} comment - A comment extracted from Babel's AST, expected to be a CommentBlock containing type definitions.
+ * @param {Function} expandType - A function that takes a type expression as a string and returns a structured representation of the type.
+ */
+function parseJSDocTypedef(typedefs, typedefTemplates, warn, comment, expandType) {
+  const {
+    type,
+    value
+  } = comment;
+  if (type !== 'CommentBlock') {
+    return;
+  }
+  const lines = value.split('\n');
+  let lastTypedef;
+  let pendingTemplates = [];
+  /**
+   * @param {string} line - The trimmed JSDoc line.
+   * @returns {boolean} True when the line held a template tag.
+   */
+  function harvestTemplate(line) {
+    let match = line.match(/@template \{(.*?)\} ([a-zA-Z0-9_$]+)/);
+    if (match) {
+      pendingTemplates.push(match[2]);
+      return true;
+    }
+    match = line.match(/@template (?:\{.*?\} )?\[([a-zA-Z0-9_$]+)=/);
+    if (match) {
+      pendingTemplates.push(match[1]);
+      return true;
+    }
+    match = line.match(/@template ([a-zA-Z0-9_$]+)(?![a-zA-Z0-9_$])/);
+    if (match) {
+      pendingTemplates.push(match[1]);
+      return true;
+    }
+    return false;
+  }
+  for (let line of lines) {
+    line = line.trim();
+    if (line[0] === '*') {
+      line = line.slice(1).trim();
+    }
+    if (line.startsWith('@template')) {
+      harvestTemplate(line);
+    } else if (line.startsWith('@typedef')) {
+      const {
+        content: def,
+        nextIndex
+      } = extractCurlyContent(line);
+      let name = line.substring(nextIndex).trim();
+      // Drop description
+      name = name.split(' ')[0];
+      lastTypedef = expandType(def);
+      // Ignore @typedef's that only refer to themselves in another file (see typedef-overwrite test)
+      if (lastTypedef !== name) {
+        typedefs[name] = lastTypedef;
+        if (pendingTemplates.length) {
+          typedefTemplates[name] = [...pendingTemplates];
+        }
+      }
+      pendingTemplates = [];
+    } else if (line.startsWith('@property')) {
+      var _lastTypedef;
+      // class @property
+      if (!lastTypedef) {
+        continue;
+      }
+      const {
+        content,
+        nextIndex
+      } = extractCurlyContent(line);
+      const rest = line.substring(nextIndex);
+      const propType = expandType(content);
+      const [name, optional] = extractNameAndOptionality(rest);
+      // console.log({name, optional, propType});
+      const finalType = annotateOptional(propType, optional);
+      if (((_lastTypedef = lastTypedef) == null ? void 0 : _lastTypedef.type) === 'object') {
+        lastTypedef.properties[name] = finalType;
+      } else {
+        warn("not an extensible type", lastTypedef);
+      }
+    } else if (line.startsWith('@callback')) {
+      const name = line.substring(9).trim();
+      typedefs[name] = 'Function';
+    }
+  }
+}
+
+/**
+ * @typedef {ReturnType<typeof parseJSDoc>} ParseJSDocReturnType
+ */
+/**
+ * @typedef {typeof expandTypeDepFree} ExpandType
+ * @typedef {ReturnType<ExpandType>} ExpandTypeReturnType
+ */
+/**
+ * Parses JSDoc comments to extract parameter type information.
+ *
+ * @param {string} src - The JSDoc comment string to parse.
+ * @param {ExpandType} [expandType] - An optional function to process the types found in the JSDoc.
+ * @returns {Record<string, ExpandTypeReturnType> | undefined} An object mapping parameter names to their parsed types, or undefined if no parameters are found.
+ */
+function parseJSDoc(src, expandType = expandTypeDepFree) {
+  // Parse something like: @param {Object} [kwargs={}] Optional arguments.
+  const regex = /@param \{(.*?)\} ([\[\]a-zA-Z0-9_$=\-\{\}\.'" ]+)/g;
+  const matches = [...src.matchAll(regex)];
+  /** @type {Record<string, ExpandTypeReturnType>} */
+  const params = Object.create(null);
+  matches.forEach(_ => {
+    const type = expandType(_[1].trim());
+    let name = _[2].trim();
+    let optional = false;
+    // Examples:
+    //   name: [kwargs={}] The configuration parameters.
+    //   name: [d = 1.0] Sample spacing
+    if (name[0] === '[') {
+      // Counting opening/closing brackets for perfect match
+      let openCloseCount = 1;
+      let i = 1;
+      for (; i < name.length; i++) {
+        const c = name[i];
+        if (c === '[') {
+          openCloseCount++;
+        } else if (c === ']') {
+          openCloseCount--;
+        }
+        if (openCloseCount === 0) {
+          break;
+        }
+      }
+      // Afterwards name will be: d = 1.0
+      name = name.substring(1, i);
+      // mark it for the type:
+      optional = true;
+    }
+    // Strip the rest (either leftover of optional value or description)
+    name = name.split(' ')[0].split('=')[0].trim();
+    const annotatedType = annotateOptional(type, optional);
+    // Turn "options.stats[].unitsName" into ['options', 'stats', 'unitsName'].
+    const parts = name.split(/[\[\]]*\./);
+    let properties = params;
+    for (const part of parts) {
+      const toptype = properties[part];
+      if (!toptype) {
+        // No toptype means we resolved as far as possible, now we can add `annotatedType`.
+        console.assert(part === parts.at(-1), 'Current part and last part should be the same.');
+        properties[part] = annotatedType;
+      } else if (toptype.type === "union") {
+        const typeObject = toptype.members.find(_ => (_ == null ? void 0 : _.type) === 'object');
+        properties = typeObject.properties;
+      } else if (toptype.type === "array") {
+        properties = toptype.elementType.properties;
+      } else if (toptype.type === "object") {
+        toptype.properties = toptype.properties || Object.create(null);
+        properties = toptype.properties;
+      } else {
+        console.warn("parseJSDoc> Skipping @param, unseen syntax detected. Please check if your JSDoc is valid or open an issue about this!", {
+          src,
+          toptype,
+          parts,
+          annotatedType
+        });
+      }
+    }
+  });
+  if (Object.keys(params).length === 0) {
+    return;
+  }
+  return params;
+}
+
+/**
+ * Infers a parameter type from its default value AST node.
+ * Returns widened types like TypeScript does (`= 0` means `number`, not
+ * literal `0`; `= null` widens to `any`).
+ * Returns `undefined` when nothing useful can be inferred — the caller then
+ * emits no check, exactly like an undocumented parameter today.
+ * Shapes match what `expandType` produces so they can be embedded as-is.
+ * @param {import('@babel/types').Node} node - The default value AST node.
+ * @returns {string | object | undefined} Inferred type or `undefined` to skip.
+ */
+function inferTypeFromDefault$1(node) {
+  if (!node) {
+    return;
+  }
+  switch (node.type) {
+    case 'NumericLiteral':
+      return 'number';
+    case 'StringLiteral':
+      return 'string';
+    case 'BooleanLiteral':
+      return 'boolean';
+    case 'BigIntLiteral':
+      return {
+        type: 'bigint'
+      };
+    case 'RegExpLiteral':
+      return 'RegExp';
+    case 'TemplateLiteral':
+      return 'string';
+    case 'ArrayExpression':
+      return {
+        type: 'array',
+        elementType: 'any'
+      };
+    case 'ObjectExpression':
+      return {
+        type: 'object',
+        properties: {}
+      };
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression':
+      return 'Function';
+    case 'NewExpression':
+      {
+        const {
+          callee
+        } = node;
+        if (callee.type === 'Identifier') {
+          return callee.name;
+        }
+        break;
+      }
+    case 'UnaryExpression':
+      {
+        const {
+          operator,
+          argument
+        } = node;
+        if (operator === '!') {
+          return 'boolean';
+        }
+        if (operator === 'void' || operator === 'typeof') {
+          return operator === 'void' ? 'undefined' : 'string';
+        }
+        if ((operator === '-' || operator === '+') && argument.type === 'NumericLiteral') {
+          return 'number';
+        }
+        if ((operator === '-' || operator === '+') && argument.type === 'BigIntLiteral') {
+          return {
+            type: 'bigint'
+          };
+        }
+        break;
+      }
+  }
+}
+
+// Declaration-site ranks: the field always beats constructor assignments,
+// like TSC where the declared type wins over assigned values.
+const FIELD_JSDOC = 3;
+const CTOR_JSDOC = 2;
+const FIELD_INFER = 1;
+const CTOR_INFER = 0;
+/**
+ * Reads the last block comment attached to a node.
+ * @param {*} node - Babel AST node.
+ * @returns {string|undefined} Comment text or undefined.
+ */
+function lastBlockComment(node) {
+  const list = node == null ? void 0 : node.leadingComments;
+  if (!list) {
+    return;
+  }
+  for (let i = list.length - 1; i >= 0; i--) {
+    if (list[i].type === 'CommentBlock') {
+      return list[i].value;
+    }
+  }
+}
+/**
+ * Extracts a `{...}`-typed JSDoc tag (`@type`, `@returns`) from a comment.
+ * @param {string|undefined} comment - Comment text.
+ * @param {string} tag - Tag name including `@`.
+ * @param {Function} expandType - String type to structured type.
+ * @returns {{type: *, raw: string}|undefined} Expanded type plus raw text.
+ */
+function tagType(comment, tag, expandType) {
+  if (!comment) {
+    return;
+  }
+  const idx = comment.search(new RegExp(`${tag}(?=[\\s{])`));
+  if (idx === -1) {
+    return;
+  }
+  const slice = comment.slice(idx);
+  if (!slice.includes('{')) {
+    return;
+  }
+  try {
+    const {
+      content
+    } = extractCurlyContent(slice);
+    if (!content || !content.trim()) {
+      return;
+    }
+    return {
+      type: expandType(content.trim()),
+      raw: content.trim()
+    };
+  } catch (_unused) {
+    // Unparseable annotation: fail open, harvest continues.
+  }
+}
+/**
+ * Reads a static property name: identifiers and string literals, including
+ * computed `['name']` forms. Anything dynamic yields undefined.
+ * @param {*} key - Babel key node.
+ * @param {boolean} computed - Whether the key position is computed.
+ * @returns {string|undefined} Property name or undefined.
+ */
+function keyName(key, computed) {
+  if (!key) {
+    return;
+  }
+  if (key.type === 'Identifier' && !computed) {
+    return key.name;
+  }
+  if (key.type === 'StringLiteral') {
+    return key.value;
+  }
+}
+/**
+ * Unwraps parenthesized and TS `as`/`satisfies` nodes.
+ * @param {*} node - Babel AST node.
+ * @returns {*} Unwrapped node.
+ */
+function unwrap(node) {
+  while (node && (node.type === 'ParenthesizedExpression' || node.type === 'TSAsExpression' || node.type === 'TSSatisfiesExpression')) {
+    node = node.expression;
+  }
+  return node;
+}
+/**
+ * Merges a harvested entry: higher rank wins the type, flags accumulate
+ * (`optional` reflects runtime reality, `@readonly` anywhere counts).
+ * Two disagreeing humans (JSDoc vs JSDoc) warn, like a TSC error.
+ * @param {Record<string, object>} fields - Collected entries by name.
+ * @param {string} name - Property name.
+ * @param {object} entry - Entry with type, rank, raw, readonly, optional.
+ * @param {Function} warn - Transpile-time warning function.
+ * @param {string} className - Class name for messages.
+ */
+function record(fields, name, entry, warn, className) {
+  const existing = fields[name];
+  if (!existing) {
+    fields[name] = entry;
+    return;
+  }
+  if (entry.jsdoc && existing.jsdoc && entry.raw !== existing.raw) {
+    warn(`harvestClassShape: ${className}.${name} has conflicting JSDoc types (${existing.raw} vs ${entry.raw})`);
+  }
+  const winner = entry.rank >= existing.rank ? entry : existing;
+  winner.readonly = existing.readonly || entry.readonly;
+  winner.optional = existing.optional || entry.optional;
+  fields[name] = winner;
+}
+/**
+ * Turns a collected entry into a type struct, applying flags.
+ * @param {object} entry - Collected entry.
+ * @returns {*} Type struct or name.
+ */
+function entryToType(entry) {
+  var _entry$type;
+  const t = (_entry$type = entry.type) != null ? _entry$type : 'any';
+  if (!entry.readonly && !entry.optional) {
+    return t;
+  }
+  if (t && typeof t === 'object') {
+    return _extends({}, t, entry.readonly ? {
+      readonly: true
+    } : {}, entry.optional ? {
+      optional: true
+    } : {});
+  }
+  const out = {
+    type: t
+  };
+  if (entry.readonly) {
+    out.readonly = true;
+  }
+  if (entry.optional) {
+    out.optional = true;
+  }
+  return out;
+}
+/**
+ * Records `this.x = ...` (or `+=`, `++`) assignments.
+ * @param {*} left - Assignment target.
+ * @param {*} right - Assigned value or undefined for op-assign/update.
+ * @param {string|undefined} comment - Leading comment text.
+ * @param {boolean} conditional - True inside conditionals (counts as optional).
+ * @param {object} ctx - Harvest context with fields, expandType, warn, className.
+ */
+function recordThisAssign(left, right, comment, conditional, ctx) {
+  var _declared$type;
+  const {
+    fields,
+    expandType,
+    warn,
+    className
+  } = ctx;
+  left = unwrap(left);
+  if (!left || left.type !== 'MemberExpression' || left.computed) {
+    return;
+  }
+  if (!left.object || left.object.type !== 'ThisExpression') {
+    return;
+  }
+  const name = keyName(left.property, false);
+  if (name === undefined) {
+    return;
+  }
+  const declared = tagType(comment, '@type', expandType);
+  if (right === undefined) {
+    // Op-assign/update (`+=`, `++`): exists, type unknown.
+    record(fields, name, {
+      type: 'any',
+      rank: CTOR_INFER,
+      jsdoc: false,
+      optional: conditional
+    }, warn, className);
+    return;
+  }
+  const inferred = inferTypeFromDefault$1(unwrap(right));
+  const type = (_declared$type = declared == null ? void 0 : declared.type) != null ? _declared$type : inferred;
+  if (type === undefined) {
+    return;
+  }
+  record(fields, name, {
+    type,
+    rank: declared ? CTOR_JSDOC : CTOR_INFER,
+    jsdoc: declared !== undefined,
+    raw: declared == null ? void 0 : declared.raw,
+    optional: conditional
+  }, warn, className);
+}
+/**
+ * Handles `Object.assign(this, {...})` with inline object literals.
+ * @param {*} node - CallExpression node.
+ * @param {boolean} conditional - True inside conditionals.
+ * @param {object} ctx - Harvest context.
+ * @returns {boolean} True when the call was `Object.assign` on `this`.
+ */
+function recordObjectAssign(node, conditional, ctx) {
+  var _callee$object, _callee$property;
+  const {
+    fields,
+    expandType,
+    warn,
+    className
+  } = ctx;
+  const {
+    callee,
+    arguments: args
+  } = node;
+  if (!callee || callee.type !== 'MemberExpression' || callee.computed) {
+    return false;
+  }
+  if (((_callee$object = callee.object) == null ? void 0 : _callee$object.type) !== 'Identifier' || callee.object.name !== 'Object') {
+    return false;
+  }
+  if (((_callee$property = callee.property) == null ? void 0 : _callee$property.type) !== 'Identifier' || callee.property.name !== 'assign') {
+    return false;
+  }
+  if (!args.length || args[0].type !== 'ThisExpression') {
+    return false;
+  }
+  for (const arg of args.slice(1)) {
+    if (!arg || arg.type !== 'ObjectExpression') {
+      continue;
+    }
+    for (const prop of arg.properties) {
+      var _declared$type2;
+      if (!prop || prop.type !== 'ObjectProperty') {
+        continue;
+      }
+      const name = keyName(prop.key, prop.computed);
+      if (name === undefined) {
+        continue;
+      }
+      const comment = lastBlockComment(prop);
+      const declared = tagType(comment, '@type', expandType);
+      const type = (_declared$type2 = declared == null ? void 0 : declared.type) != null ? _declared$type2 : inferTypeFromDefault$1(unwrap(prop.value));
+      if (type === undefined) {
+        continue;
+      }
+      record(fields, name, {
+        type,
+        rank: declared ? CTOR_JSDOC : CTOR_INFER,
+        jsdoc: declared !== undefined,
+        raw: declared == null ? void 0 : declared.raw,
+        optional: conditional
+      }, warn, className);
+    }
+  }
+  return true;
+}
+/**
+ * Walks an expression for `this.x` writes. Stops at function boundaries:
+ * deferred writes (callbacks) are out of scope.
+ * @param {*} expr - Babel expression node.
+ * @param {boolean} conditional - True inside conditionals.
+ * @param {object} ctx - Harvest context.
+ * @param {*} stmt - Enclosing statement carrying leading comments.
+ */
+function walkExpression(expr, conditional, ctx, stmt) {
+  if (!expr) {
+    return;
+  }
+  switch (expr.type) {
+    case 'AssignmentExpression':
+      {
+        const comment = lastBlockComment(stmt);
+        if (expr.operator === '=') {
+          recordThisAssign(expr.left, expr.right, comment, conditional, ctx);
+          walkExpression(expr.right, conditional, ctx, stmt);
+        } else {
+          recordThisAssign(expr.left, undefined, comment, conditional, ctx);
+        }
+        break;
+      }
+    case 'UpdateExpression':
+      recordThisAssign(expr.argument, undefined, lastBlockComment(stmt), conditional, ctx);
+      break;
+    case 'SequenceExpression':
+      for (const each of expr.expressions) {
+        walkExpression(each, conditional, ctx, stmt);
+      }
+      break;
+    case 'LogicalExpression':
+      walkExpression(expr.right, true, ctx, stmt);
+      break;
+    case 'ConditionalExpression':
+      walkExpression(expr.consequent, true, ctx, stmt);
+      walkExpression(expr.alternate, true, ctx, stmt);
+      break;
+    case 'CallExpression':
+      recordObjectAssign(expr, conditional, ctx);
+      break;
+  }
+}
+/**
+ * Walks a statement for `this.x` writes. Conditional wrappers mark entries
+ * optional; nested functions are boundaries.
+ * @param {*} st - Babel statement node.
+ * @param {boolean} conditional - True inside conditionals.
+ * @param {object} ctx - Harvest context.
+ */
+function walkStatement(st, conditional, ctx) {
+  if (!st) {
+    return;
+  }
+  switch (st.type) {
+    case 'BlockStatement':
+      for (const each of st.body) {
+        walkStatement(each, conditional, ctx);
+      }
+      break;
+    case 'ExpressionStatement':
+      walkExpression(st.expression, conditional, ctx, st);
+      break;
+    case 'ReturnStatement':
+      walkExpression(st.argument, conditional, ctx, st);
+      break;
+    case 'IfStatement':
+      walkStatement(st.consequent, true, ctx);
+      walkStatement(st.alternate, true, ctx);
+      break;
+    case 'WhileStatement':
+    case 'ForStatement':
+    case 'ForInStatement':
+    case 'ForOfStatement':
+      walkStatement(st.body, true, ctx);
+      break;
+    case 'DoWhileStatement':
+      walkStatement(st.body, conditional, ctx);
+      break;
+    case 'SwitchStatement':
+      for (const each of st.cases) {
+        for (const consequent of each.consequent) {
+          walkStatement(consequent, true, ctx);
+        }
+      }
+      break;
+    case 'TryStatement':
+      walkStatement(st.block, conditional, ctx);
+      if (st.handler) {
+        walkStatement(st.handler.body, true, ctx);
+      }
+      if (st.finalizer) {
+        walkStatement(st.finalizer, conditional, ctx);
+      }
+      break;
+    case 'LabeledStatement':
+      walkStatement(st.body, conditional, ctx);
+      break;
+  }
+}
+/**
+ * Reads the single parameter name of a setter.
+ * @param {*} param - Babel parameter node.
+ * @returns {string|undefined} Name or undefined.
+ */
+function setterParamName(param) {
+  if (!param) {
+    return;
+  }
+  if (param.type === 'Identifier') {
+    return param.name;
+  }
+  if (param.type === 'AssignmentPattern' && param.left.type === 'Identifier') {
+    return param.left.name;
+  }
+}
+/**
+ * Reads a setter's value type: its `@param` JSDoc first, `@type` fallback.
+ * @param {*} set - Babel ClassMethod (kind set) node.
+ * @param {Function} expandType - String type to structured type.
+ * @returns {{type: *, raw: string|undefined, jsdoc: boolean}} Type plus metadata.
+ */
+function setterType(set, expandType) {
+  const setComment = lastBlockComment(set);
+  const paramName = setterParamName(set.params[0]);
+  const params = parseJSDoc(setComment != null ? setComment : '', expandType);
+  if (paramName && params && params[paramName] !== undefined) {
+    return {
+      type: params[paramName],
+      raw: undefined,
+      jsdoc: true
+    };
+  }
+  const tagged = tagType(setComment, '@type', expandType);
+  if (tagged) {
+    return {
+      type: tagged.type,
+      raw: tagged.raw,
+      jsdoc: true
+    };
+  }
   return {
-    content,
-    nextIndex: k + 1
+    type: 'any',
+    raw: undefined,
+    jsdoc: false
   };
 }
 /**
- * Parses JSDoc comments to extract and expand typedefs and their associated properties.
- *
- * It iterates through the lines of a `CommentBlock` from the Babel AST, looking for `@typedef` and `@property`
- * annotations. When it finds a typedef, it stores it in the `typedefs` record. When it finds a property,
- * it adds it to the last found typedef if it is an object type.
- * @param {Record<string, object>} typedefs - An object to store typedefs, mapping type names to their expanded definitions.
- * @param {Console["warn"]} warn - A warn function used for emitting warnings about non-extensible types.
- * @param {import("@babel/types").Comment} comment - A comment extracted from Babel's AST, expected to be a CommentBlock containing type definitions.
- * @param {Function} expandType - A function that takes a type expression as a string and returns a structured representation of the type.
+ * Harvests the instance shape of a class: field declarations (JSDoc wins,
+ * else inferred), constructor `this.x` writes (field site wins conflicts),
+ * methods as `Function`, getter/setter pairs as writable and getter-only as
+ * readonly. Statics, privates and dynamic keys are skipped.
+ * @param {*} node - Babel ClassDeclaration node.
+ * @param {object} opts - Options with expandType and warn.
+ * @param {Function} opts.expandType - String type to structured type.
+ * @param {Function} opts.warn - Transpile-time warning function.
+ * @returns {{name: string, shape: object}|undefined} Class name plus object shape.
  */
-function parseJSDocTypedef(typedefs, warn, comment, expandType) {
-  const {
-    type,
-    value
-  } = comment;
-  if (type !== 'CommentBlock') {
+function harvestClassShape(node, {
+  expandType,
+  warn
+}) {
+  const id = node == null ? void 0 : node.id;
+  if (!id || id.type !== 'Identifier' || !id.name) {
     return;
   }
-  const lines = value.split('\n');
-  let lastTypedef;
-  for (let line of lines) {
-    line = line.trim();
-    if (line[0] === '*') {
-      line = line.slice(1).trim();
+  const className = id.name;
+  const ctx = {
+    fields: {},
+    gets: {},
+    sets: {},
+    expandType,
+    warn,
+    className
+  };
+  let ctor = null;
+  for (const el of node.body.body) {
+    if (el.type === 'ClassPrivateProperty' || el.type === 'ClassPrivateMethod') {
+      continue;
     }
-    if (line.startsWith('@typedef')) {
-      const {
-        content: def,
-        nextIndex
-      } = extractCurlyContent(line);
-      let name = line.substring(nextIndex).trim();
-      // Drop description
-      name = name.split(' ')[0];
-      lastTypedef = expandType(def);
-      // Ignore @typedef's that only refer to themselves in another file (see typedef-overwrite test)
-      if (lastTypedef !== name) {
-        typedefs[name] = lastTypedef;
+    const name = keyName(el.key, el.computed);
+    if (name === undefined) {
+      continue;
+    }
+    if (el.type === 'ClassProperty' || el.type === 'PropertyDefinition') {
+      var _declared$type3;
+      if (el.static || el.declare) {
+        continue;
       }
-    } else if (line.startsWith('@property')) {
-      var _lastTypedef;
-      // class @property
-      if (!lastTypedef) {
+      const comment = lastBlockComment(el);
+      const declared = tagType(comment, '@type', expandType);
+      const inferred = el.value ? inferTypeFromDefault$1(unwrap(el.value)) : undefined;
+      const type = (_declared$type3 = declared == null ? void 0 : declared.type) != null ? _declared$type3 : inferred;
+      if (type === undefined) {
         continue;
       }
-      const {
-        content,
-        nextIndex
-      } = extractCurlyContent(line);
-      const rest = line.substring(nextIndex);
-      const propType = expandType(content);
-      const [name, optional] = extractNameAndOptionality(rest);
-      // console.log({name, optional, propType});
-      const finalType = annotateOptional(propType, optional);
-      if (((_lastTypedef = lastTypedef) == null ? void 0 : _lastTypedef.type) === 'object') {
-        lastTypedef.properties[name] = finalType;
-      } else {
-        warn("not an extensible type", lastTypedef);
+      record(ctx.fields, name, {
+        type,
+        rank: declared ? FIELD_JSDOC : FIELD_INFER,
+        jsdoc: declared !== undefined,
+        raw: declared == null ? void 0 : declared.raw,
+        readonly: el.readonly === true || (comment ? /@readonly(?![\w])/.test(comment) : false),
+        optional: el.optional === true
+      }, warn, className);
+    } else if (el.type === 'ClassMethod' || el.type === 'ClassPrivateMethod') {
+      if (el.static) {
+        continue;
       }
-    } else if (line.startsWith('@callback')) {
-      const name = line.substring(9).trim();
-      typedefs[name] = 'Function';
+      if (el.kind === 'constructor') {
+        ctor = el;
+      } else if (el.kind === 'method') {
+        var _ctx$fields$name;
+        ctx.fields[name] = (_ctx$fields$name = ctx.fields[name]) != null ? _ctx$fields$name : {
+          type: 'Function',
+          rank: FIELD_INFER,
+          jsdoc: false
+        };
+      } else if (el.kind === 'get') {
+        ctx.gets[name] = el;
+      } else if (el.kind === 'set') {
+        ctx.sets[name] = el;
+      }
+    }
+  }
+  for (const name of Object.keys(ctx.gets)) {
+    var _tagType, _ref, _getType$type, _getType$raw;
+    const get = ctx.gets[name];
+    const set = ctx.sets[name];
+    const getComment = lastBlockComment(get);
+    const getType = (_tagType = tagType(getComment, '@type', expandType)) != null ? _tagType : tagType(getComment, '@returns', expandType);
+    const setInfo = set ? setterType(set, expandType) : undefined;
+    const type = (_ref = (_getType$type = getType == null ? void 0 : getType.type) != null ? _getType$type : setInfo == null ? void 0 : setInfo.type) != null ? _ref : 'any';
+    record(ctx.fields, name, {
+      type,
+      rank: getType || setInfo != null && setInfo.jsdoc ? FIELD_JSDOC : FIELD_INFER,
+      jsdoc: Boolean(getType || (setInfo == null ? void 0 : setInfo.jsdoc)),
+      raw: (_getType$raw = getType == null ? void 0 : getType.raw) != null ? _getType$raw : setInfo == null ? void 0 : setInfo.raw,
+      readonly: !set
+    }, warn, className);
+  }
+  for (const name of Object.keys(ctx.sets)) {
+    if (ctx.gets[name]) {
+      continue;
+    }
+    const setInfo = setterType(ctx.sets[name], expandType);
+    record(ctx.fields, name, {
+      type: setInfo.type,
+      rank: setInfo.jsdoc ? FIELD_JSDOC : FIELD_INFER,
+      jsdoc: setInfo.jsdoc,
+      raw: setInfo.raw
+    }, warn, className);
+  }
+  if (ctor && ctor.body) {
+    for (const st of ctor.body.body) {
+      walkStatement(st, false, ctx);
     }
   }
+  const properties = {};
+  for (const name of Object.keys(ctx.fields)) {
+    properties[name] = entryToType(ctx.fields[name]);
+  }
+  if (!Object.keys(properties).length) {
+    return;
+  }
+  return {
+    name: className,
+    shape: {
+      type: 'object',
+      properties
+    }
+  };
 }
 
 /**
@@ -1190,89 +2262,6 @@ function nodeIsFunctionLike(node) {
   return false;
 }
 
-/**
- * @typedef {ReturnType<typeof parseJSDoc>} ParseJSDocReturnType
- */
-/**
- * @typedef {typeof expandTypeDepFree} ExpandType
- * @typedef {ReturnType<ExpandType>} ExpandTypeReturnType
- */
-/**
- * Parses JSDoc comments to extract parameter type information.
- *
- * @param {string} src - The JSDoc comment string to parse.
- * @param {ExpandType} [expandType] - An optional function to process the types found in the JSDoc.
- * @returns {Record<string, ExpandTypeReturnType> | undefined} An object mapping parameter names to their parsed types, or undefined if no parameters are found.
- */
-function parseJSDoc(src, expandType = expandTypeDepFree) {
-  // Parse something like: @param {Object} [kwargs={}] Optional arguments.
-  const regex = /@param \{(.*?)\} ([\[\]a-zA-Z0-9_$=\-\{\}\.'" ]+)/g;
-  const matches = [...src.matchAll(regex)];
-  /** @type {Record<string, ExpandTypeReturnType>} */
-  const params = Object.create(null);
-  matches.forEach(_ => {
-    const type = expandType(_[1].trim());
-    let name = _[2].trim();
-    let optional = false;
-    // Examples:
-    //   name: [kwargs={}] The configuration parameters.
-    //   name: [d = 1.0] Sample spacing
-    if (name[0] === '[') {
-      // Counting opening/closing brackets for perfect match
-      let openCloseCount = 1;
-      let i = 1;
-      for (; i < name.length; i++) {
-        const c = name[i];
-        if (c === '[') {
-          openCloseCount++;
-        } else if (c === ']') {
-          openCloseCount--;
-        }
-        if (openCloseCount === 0) {
-          break;
-        }
-      }
-      // Afterwards name will be: d = 1.0
-      name = name.substring(1, i);
-      // mark it for the type:
-      optional = true;
-    }
-    // Strip the rest (either leftover of optional value or description)
-    name = name.split(' ')[0].split('=')[0].trim();
-    const annotatedType = annotateOptional(type, optional);
-    // Turn "options.stats[].unitsName" into ['options', 'stats', 'unitsName'].
-    const parts = name.split(/[\[\]]*\./);
-    let properties = params;
-    for (const part of parts) {
-      const toptype = properties[part];
-      if (!toptype) {
-        // No toptype means we resolved as far as possible, now we can add `annotatedType`.
-        console.assert(part === parts.at(-1), 'Current part and last part should be the same.');
-        properties[part] = annotatedType;
-      } else if (toptype.type === "union") {
-        const typeObject = toptype.members.find(_ => (_ == null ? void 0 : _.type) === 'object');
-        properties = typeObject.properties;
-      } else if (toptype.type === "array") {
-        properties = toptype.elementType.properties;
-      } else if (toptype.type === "object") {
-        toptype.properties = toptype.properties || Object.create(null);
-        properties = toptype.properties;
-      } else {
-        console.warn("parseJSDoc> Skipping @param, unseen syntax detected. Please check if your JSDoc is valid or open an issue about this!", {
-          src,
-          toptype,
-          parts,
-          annotatedType
-        });
-      }
-    }
-  });
-  if (Object.keys(params).length === 0) {
-    return;
-  }
-  return params;
-}
-
 /**
  * @param {string} src - JSDoc comment of the setter.
  * @param {Function} expandType - The expandType function.
@@ -1305,9 +2294,6 @@ function parseJSDocSetter(src, expandType = expandTypeDepFree) {
 function parseJSDocTemplates(src, expandType = expandTypeDepFree) {
   const regexTemplateTyped = /@template \{(.*?)\} ([a-zA-Z0-9_$=]+)/g;
   const matches = [...src.matchAll(regexTemplateTyped)];
-  if (!matches.length) {
-    return;
-  }
   /** @type {Record<string, ExpandTypeReturnType>} */
   const templates = Object.create(null);
   matches.forEach(_ => {
@@ -1315,22 +2301,23 @@ function parseJSDocTemplates(src, expandType = expandTypeDepFree) {
     const name = _[2].trim();
     templates[name] = type;
   });
-  return templates;
-}
-
-function _extends() {
-  _extends = Object.assign ? Object.assign.bind() : function (target) {
-    for (var i = 1; i < arguments.length; i++) {
-      var source = arguments[i];
-      for (var key in source) {
-        if (Object.prototype.hasOwnProperty.call(source, key)) {
-          target[key] = source[key];
-        }
-      }
+  // `@template [A=X]` defaults: constraint X under name A.
+  const regexTemplateDefault = /@template \[([a-zA-Z0-9_$]+)=([^\]]+)\]/g;
+  for (const match of src.matchAll(regexTemplateDefault)) {
+    templates[match[1]] = expandType(match[2].trim());
+  }
+  // Bare `@template T`: unconstrained, stands in as any.
+  const regexTemplateBare = /@template ([a-zA-Z0-9_$]+)(?![a-zA-Z0-9_$])/g;
+  for (const match of src.matchAll(regexTemplateBare)) {
+    const name = match[1];
+    if (!(name in templates)) {
+      templates[name] = 'any';
     }
-    return target;
-  };
-  return _extends.apply(this, arguments);
+  }
+  if (!Object.keys(templates).length) {
+    return;
+  }
+  return templates;
 }
 
 /**
@@ -3516,6 +4503,9 @@ class Stringifier {
  * @typedef {object} Options
  * @property {boolean} [forceCurly] - Determines whether curly braces are enforced in Stringifier.
  * @property {boolean} [validateDivision] - Indicates whether division operations should be validated.
+ * @property {boolean} [inspectIndexedAccess] - Indicates whether indexed accesses
+ * like `arr[i]` should be wrapped for bounds and integer validation. Disable
+ * to drop indexed access inspection entirely. Defaults to true.
  * @property {import('./parseJSDoc.js').ExpandType} [expandType] - A function that expands shorthand types into full descriptions.
  * @property {string} [filename] - The name of a file to which the instance pertains.
  * @property {boolean} [addHeader] - Whether to add import declarations headers. Defaults to true.
@@ -3528,6 +4518,7 @@ class Asserter extends Stringifier {
   constructor({
     forceCurly = true,
     validateDivision = true,
+    inspectIndexedAccess = true,
     expandType = expandTypeDepFree,
     filename,
     addHeader = true,
@@ -3583,10 +4574,13 @@ class Asserter extends Stringifier {
     };
     /** @type {Record<string, object>} */
     this.typedefs = {};
+    /** @type {Record<string, string[]>} */
+    this.typedefTemplates = {};
     /** @type {string[]} */
     this.addLaterImportNamespaceSpecifier = [];
     this.forceCurly = forceCurly;
     this.validateDivision = validateDivision;
+    this.inspectIndexedAccess = inspectIndexedAccess;
     // @todo collect every type + manually validate as test set
     // + implement expandType using Babel Flow type parser aswell
     this.expandType = expandType;
@@ -3644,6 +4638,21 @@ class Asserter extends Stringifier {
     const id_ = this.toSource(id);
     let out = super.ClassDeclaration(node);
     out += `${this.spaces}registerClass(${id_});`;
+    const harvested = harvestClassShape(node, {
+      expandType: this.expandType,
+      warn: this.warn.bind(this)
+    });
+    if (harvested) {
+      // Hand-written typedefs win: emitting a second registerTypedef for the
+      // same name would be last-wins deterministic but noisy, so the harvest
+      // step skips names already present in this.typedefs (populated in File).
+      if (this.typedefs[harvested.name]) {
+        this.warn(`harvestClassShape: skipping harvested shape for '${harvested.name}', hand-written typedef wins`);
+      } else {
+        const json = simplifyTypeToSource(harvested.shape);
+        out += `\n${this.spaces}registerTypedef('${harvested.name}', ${json});`;
+      }
+    }
     return out;
   }
   /**
@@ -4393,6 +5402,9 @@ class Asserter extends Stringifier {
       object,
       property
     } = node;
+    if (!this.inspectIndexedAccess) {
+      return super.MemberExpression(node);
+    }
     if (!computed || object.type === 'Super') {
       return super.MemberExpression(node);
     }
@@ -4409,6 +5421,43 @@ class Asserter extends Stringifier {
       if (parent.type === 'UnaryExpression' && parent.operator === 'delete' && parent.argument === node) {
         return super.MemberExpression(node);
       }
+      // Destructuring, rest and loop targets are assigned to, never read.
+      if (parent.type === 'ArrayPattern') {
+        return super.MemberExpression(node);
+      }
+      if (parent.type === 'RestElement' && parent.argument === node) {
+        return super.MemberExpression(node);
+      }
+      if (parent.type === 'ObjectProperty' && parent.value === node) {
+        // `({p: a[i]})` reads but `({p: a[i]} = ...)` writes: bypass inside patterns only.
+        const grandparent = this.parents[this.parents.findLastIndex(_ => _ === parent) - 1];
+        if ((grandparent == null ? void 0 : grandparent.type) === 'ObjectPattern') {
+          return super.MemberExpression(node);
+        }
+      }
+      if (parent.type === 'AssignmentPattern' && parent.left === node) {
+        return super.MemberExpression(node);
+      }
+      if ((parent.type === 'ForOfStatement' || parent.type === 'ForInStatement') && parent.left === node) {
+        return super.MemberExpression(node);
+      }
+      // Method calls and tags carry their base as `this`; wrapping the callee
+      // would silently rebind it to undefined.
+      if ((parent.type === 'CallExpression' || parent.type === 'OptionalCallExpression') && parent.callee === node) {
+        return super.MemberExpression(node);
+      }
+      if (parent.type === 'TaggedTemplateExpression' && parent.tag === node) {
+        return super.MemberExpression(node);
+      }
+      // `new a[i](...)` must stay `new (inspectIndexedAccess(...))(...)`:
+      // without parens it parses as `(new inspectIndexedAccess(...))(...)`,
+      // constructing the wrapper instead of the accessed value.
+      if (parent.type === 'NewExpression' && parent.callee === node) {
+        const _object_ = this.toSource(object);
+        const _property_ = this.toSource(property);
+        const _loc5 = this.getName(node);
+        return `(inspectIndexedAccess(${_object_}, ${_property_}, ${JSON.stringify(_loc5)}))`;
+      }
     }
     const object_ = this.toSource(object);
     const property_ = this.toSource(property);
@@ -4451,7 +5500,7 @@ class Asserter extends Stringifier {
     if (comments) {
       for (const comment of comments) {
         const warn = this.warn.bind(this);
-        parseJSDocTypedef(this.typedefs, warn, comment, this.expandType);
+        parseJSDocTypedef(this.typedefs, this.typedefTemplates, warn, comment, this.expandType);
       }
     }
     //console.log("this.typedefs", this.typedefs);
@@ -4459,7 +5508,8 @@ class Asserter extends Stringifier {
     for (const name in this.typedefs) {
       const typedef = this.typedefs[name];
       const json = simplifyTypeToSource(typedef);
-      out += `registerTypedef('${name}', ${json});\n`;
+      const params = this.typedefTemplates[name];
+      out += params != null && params.length ? `registerTypedef('${name}', ${json}, ${JSON.stringify(params)});\n` : `registerTypedef('${name}', ${json});\n`;
     }
     const code = this.toSource(program) + '\n';
     out += code;
@@ -4729,7 +5779,13 @@ function toSourceBabelTS(node) {
       {
         const name = toSourceBabelTS(node.typeName);
         if (!node.typeParameters) {
-          // console.log(`node.typeName.name=${node.typeName.name} name=${name}`, node);
+          // Bare `Object` is the empty object type, matching expandType().
+          if (name === 'Object') {
+            return {
+              type: 'object',
+              properties: {}
+            };
+          }
           // Bare reference: Identifier gives name, TSQualifiedName gives dotted path.
           return name;
         }
@@ -4790,6 +5846,8 @@ function toSourceBabelTS(node) {
       }
     case 'TSStringKeyword':
       return 'string';
+    case 'TSSymbolKeyword':
+      return 'symbol';
     case 'TSNumberKeyword':
       return 'number';
     case 'TSIntersectionType':
@@ -4871,6 +5929,8 @@ function toSourceBabelTS(node) {
     case 'ParenthesizedType':
       // fall-through for parentheses
       return toSourceBabelTS(node.type);
+    case 'TSParenthesizedType':
+      return toSourceBabelTS(node.typeAnnotation);
     case 'LastTypeNode':
       return toSourceBabelTS(node.qualifier);
     case 'TSTypeQuery':
@@ -4879,11 +5939,120 @@ function toSourceBabelTS(node) {
         type: 'typeof',
         argument
       };
+    case 'TSConditionalType':
+      {
+        const checkType = toSourceBabelTS(node.checkType);
+        const extendsType = toSourceBabelTS(node.extendsType);
+        const trueType = toSourceBabelTS(node.trueType);
+        const falseType = toSourceBabelTS(node.falseType);
+        return {
+          type: 'condition',
+          checkType,
+          extendsType,
+          trueType,
+          falseType
+        };
+      }
+    case 'TSIndexedAccessType':
+      {
+        const index = toSourceBabelTS(node.indexType);
+        const object = toSourceBabelTS(node.objectType);
+        return {
+          type: 'indexedAccess',
+          index,
+          object
+        };
+      }
+    case 'TSMappedType':
+      {
+        const param = node.typeParameter;
+        const nameNode = param == null ? void 0 : param.name;
+        const element = typeof nameNode === 'string' ? nameNode : toSourceBabelTS(nameNode);
+        const iterable = toSourceBabelTS(param == null ? void 0 : param.constraint);
+        const result = toSourceBabelTS(node.typeAnnotation);
+        const out = {
+          type: 'mapping',
+          iterable,
+          element,
+          result
+        };
+        if (node.nameType) {
+          out.nameType = toSourceBabelTS(node.nameType);
+        }
+        if (node.optional !== undefined && node.optional !== false && node.optional !== null) {
+          out.question = node.optional === '-' ? '-' : node.optional === '+' ? '+' : '?';
+        }
+        if (node.readonly !== undefined && node.readonly !== false && node.readonly !== null) {
+          out.readonly = node.readonly === '-' ? '-' : node.readonly === '+' ? '+' : 'readonly';
+        }
+        return out;
+      }
+    case 'TSTypeAnnotation':
+      return toSourceBabelTS(node.typeAnnotation);
+    case 'TSTypeLiteral':
+      {
+        const _properties = {};
+        let indexSignatures;
+        for (const member of (_node$members = node.members) != null ? _node$members : []) {
+          var _node$members;
+          if (member.type === 'TSIndexSignature') {
+            var _indexSignatures;
+            indexSignatures = (_indexSignatures = indexSignatures) != null ? _indexSignatures : [];
+            indexSignatures.push(toSourceBabelTS(member));
+          } else if (member.type === 'TSPropertySignature') {
+            const name = toSourceBabelTS(member.key);
+            let type = toSourceBabelTS(member.typeAnnotation);
+            if (member.optional) {
+              if (type && typeof type === 'object') type.optional = true;else type = {
+                type,
+                optional: true
+              };
+            }
+            if (member.readonly) {
+              if (type && typeof type === 'object') type.readonly = true;else type = {
+                type,
+                readonly: true
+              };
+            }
+            _properties[name] = type;
+          } else {
+            console.warn('TSTypeLiteral: unhandled member', member.type);
+          }
+        }
+        const ret = {
+          type: 'object'
+        };
+        if (Object.keys(_properties).length) {
+          ret.properties = _properties;
+        }
+        if (indexSignatures) {
+          ret.indexSignatures = indexSignatures;
+        }
+        return ret;
+      }
+    case 'TSIndexSignature':
+      {
+        var _node$parameters;
+        const indexType = toSourceBabelTS(node.typeAnnotation);
+        const indexParameters = ((_node$parameters = node.parameters) != null ? _node$parameters : []).map(toSourceBabelTS);
+        return {
+          type: 'indexSignature',
+          indexType,
+          indexParameters
+        };
+      }
     case 'TSTypeOperator':
       if (node.operator === 'readonly') {
         // readonly erased at runtime, same shape as the inner type.
         return toSourceBabelTS(node.typeAnnotation);
       }
+      if (node.operator === 'keyof') {
+        const keyofArg = toSourceBabelTS(node.typeAnnotation);
+        return {
+          type: 'keyof',
+          argument: keyofArg
+        };
+      }
       console.warn('unimplemented TSTypeOperator', node.operator);
       return 'any';
     case 'TSQualifiedName':
@@ -5014,6 +6183,8 @@ class JSDocAnnotator {
     this.parents = [];
     /** @type {Record<string, object>} */
     this.typedefs = {};
+    /** @type {Record<string, string[]>} */
+    this.typedefTemplates = {};
     /** @type {import('./parseJSDoc.js').ExpandType} */
     this.expandType = options.expandType || expandTypeDepFree;
   }
@@ -5030,7 +6201,7 @@ class JSDocAnnotator {
       if (comments) {
         for (const comment of comments) {
           const warn = console.warn.bind(console);
-          parseJSDocTypedef(this.typedefs, warn, comment, this.expandType);
+          parseJSDocTypedef(this.typedefs, this.typedefTemplates, warn, comment, this.expandType);
         }
       }
       this.traverse(ast.program);