@kernlang/core 3.3.9 → 3.4.0

package/dist/importer.js

@@ -44,6 +44,16 @@ function typeToString(typeNode, source) {
     // consumes the value as a string either way.
     return /\s/.test(raw) ? `"${raw.replace(/"/g, '\\"')}"` : raw;
 }
+/** Slice 2f — extract `<T, U extends Foo = Bar>` from any declaration that
+ *  carries typeParameters and return a `generics="..."` attribute fragment
+ *  ready to splice into a KERN line. Returns empty string when there are none. */
+function genericsAttr(typeParameters, source) {
+    if (!typeParameters || typeParameters.length === 0)
+        return '';
+    const parts = typeParameters.map((tp) => tp.getText(source));
+    const block = `<${parts.join(', ')}>`;
+    return ` generics="${escapeKernString(block)}"`;
+}
 function getJSDoc(node, source) {
     const jsDocs = node.jsDoc;
     if (!jsDocs || jsDocs.length === 0)
@@ -64,7 +74,7 @@ function _indent(lines, depth) {
     const prefix = '  '.repeat(depth);
     return lines.map((l) => `${prefix}${l}`);
 }
-function escapeKernString(s) {
+export function escapeKernString(s) {
     return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
 function formatParams(params, source) {
@@ -73,11 +83,153 @@ function formatParams(params, source) {
         const name = p.name.getText(source);
         const type = typeToString(p.type, source);
         const optional = p.questionToken ? '?' : '';
+        // Codex review fix: variadic `...` was dropped by the legacy serializer.
+        // Without this, `function f(...[first]: T[])` and `function f(...args: T[])`
+        // both round-tripped without their rest marker, silently changing the
+        // call signature.
+        const dots = p.dotDotDotToken ? '...' : '';
         const defaultVal = p.initializer ? `=${p.initializer.getText(source)}` : '';
-        return type ? `${name}${optional}:${type}${defaultVal}` : `${name}${optional}${defaultVal}`;
+        return type ? `${dots}${name}${optional}:${type}${defaultVal}` : `${dots}${name}${optional}${defaultVal}`;
     })
         .join(',');
 }
+/**
+ * Slice 3c — try to emit fn parameters as structured `param` child nodes
+ * (for ValueIR canonicalisation of defaults). Returns the child lines on
+ * success, or `null` if the signature contains any feature not yet
+ * supported by structured params: optional `?`, variadic `...`, or
+ * destructuring patterns. Producers fall back to the legacy `params="..."`
+ * string for those signatures (all-or-nothing per signature).
+ *
+ * Caller is responsible for indenting the returned lines and omitting the
+ * `params="..."` attribute from the parent.
+ */
+function tryFormatParamChildren(parameters, source) {
+    if (parameters.length === 0)
+        return [];
+    for (const p of parameters) {
+        // Slice 3c-extension: optional `?`, variadic `...`, and destructured
+        // `{a,b}` / `[x,y]` are now structurable via `optional=true` /
+        // `variadic=true` / `binding`+`element` children (gates dropped).
+        // Anything else on the LHS still bails to legacy.
+        if (!ts.isIdentifier(p.name) && !ts.isObjectBindingPattern(p.name) && !ts.isArrayBindingPattern(p.name)) {
+            return null;
+        }
+        // Multi-line types (inline object shapes spread across lines) can't be
+        // round-tripped through a single-line `type="..."` quoted attribute —
+        // KERN's tokeniser treats newlines as record separators. Leave the
+        // whole signature legacy when any param has a multi-line type.
+        if (p.type && /\n/.test(p.type.getText(source)))
+            return null;
+    }
+    const lines = [];
+    for (const p of parameters) {
+        const isObj = ts.isObjectBindingPattern(p.name);
+        const isArr = ts.isArrayBindingPattern(p.name);
+        // Codex P1 fix: read the RAW type text here (not via `typeToString`,
+        // which pre-quotes whitespace types like `"string | null"`). Structured
+        // `param` children always wrap the type in quotes, so a pre-quoted
+        // value would double-wrap to `type="\"string | null\""` — invalid TS
+        // (the resulting fn would have `x: "string | null"` as a string-literal
+        // type, not a union). Legacy `params="..."` callers still go through
+        // `typeToString` and its space-aware pre-quoting.
+        const type = p.type ? p.type.getText(source) : '';
+        if (isObj || isArr) {
+            // Slice 3c-extension #3: destructured param. Convert the binding pattern
+            // to `binding`/`element` child lines (slice 3d's nodes). Bail to legacy
+            // if the pattern uses rest/defaults/nesting, since slice 3d's structured
+            // form doesn't represent those — the whole signature falls back to
+            // `params="..."` so the parent can still emit valid TS.
+            //
+            // Codex review fix: `function f(...[first]: T[])` (variadic + array
+            // destructure) is valid TS but the structured form has no slot for the
+            // outer `...`. Bail to legacy so the rest marker is preserved verbatim
+            // in `params="..."` rather than silently dropped on round-trip.
+            if (p.dotDotDotToken)
+                return null;
+            const childLines = tryFormatParamBindingPattern(p.name, source);
+            if (childLines === null)
+                return null;
+            // The destructured-param header line carries no `name=`. Type / optional
+            // / default still apply to the whole pattern: `({a,b}: T = {a:1,b:2})`.
+            const parts = ['param'];
+            if (type)
+                parts.push(`type="${escapeKernString(type)}"`);
+            if (p.questionToken)
+                parts.push('optional=true');
+            if (p.initializer)
+                parts.push(`value={{ ${p.initializer.getText(source)} }}`);
+            lines.push(parts.join(' '));
+            for (const child of childLines)
+                lines.push(`  ${child}`);
+            continue;
+        }
+        const name = p.name.getText(source);
+        const parts = [`param name=${name}`];
+        if (type)
+            parts.push(`type="${escapeKernString(type)}"`);
+        if (p.questionToken)
+            parts.push('optional=true');
+        if (p.dotDotDotToken)
+            parts.push('variadic=true');
+        if (p.initializer) {
+            parts.push(`value={{ ${p.initializer.getText(source)} }}`);
+        }
+        lines.push(parts.join(' '));
+    }
+    return lines;
+}
+/**
+ * Slice 3c-extension #3 — convert a TS parameter `BindingPattern` (object or
+ * array) into structured `binding` / `element` KERN child lines (slice 3d's
+ * shape). Returns null when the pattern uses features the structured form
+ * can't represent: rest (`...rest`), defaults (`{a = 1}`), or nested patterns
+ * (`{a: {b}}`). Caller falls back to legacy `params="..."` when null.
+ *
+ * Mirrors `tryFormatDestructure`'s sub-branch for slice 3d, but tightened to
+ * just the LHS pattern (no source/kind/type — those live on the param node).
+ */
+function tryFormatParamBindingPattern(pattern, source) {
+    const childLines = [];
+    if (ts.isObjectBindingPattern(pattern)) {
+        for (const el of pattern.elements) {
+            if (el.dotDotDotToken)
+                return null;
+            if (el.initializer)
+                return null;
+            if (!ts.isIdentifier(el.name))
+                return null;
+            const localName = el.name.getText(source);
+            let line = `binding name=${localName}`;
+            if (el.propertyName) {
+                if (!ts.isIdentifier(el.propertyName))
+                    return null;
+                line += ` key=${el.propertyName.getText(source)}`;
+            }
+            childLines.push(line);
+        }
+    }
+    else {
+        let idx = 0;
+        for (const el of pattern.elements) {
+            if (ts.isOmittedExpression(el)) {
+                idx++;
+                continue;
+            }
+            if (el.dotDotDotToken)
+                return null;
+            if (el.initializer)
+                return null;
+            if (!ts.isIdentifier(el.name))
+                return null;
+            childLines.push(`element name=${el.name.getText(source)} index=${idx}`);
+            idx++;
+        }
+    }
+    if (childLines.length === 0)
+        return null;
+    return childLines;
+}
 function getBodyText(body, source) {
     if (!body)
         return undefined;
@@ -151,6 +303,7 @@ function convertTypeAlias(node, source) {
     const lines = [];
     const name = node.name.getText(source);
     const exp = isExported(node) ? ' export=true' : '';
+    const generics = genericsAttr(node.typeParameters, source);
     const doc = getJSDoc(node, source);
     if (doc)
         lines.push(`doc text="${escapeKernString(doc)}"`);
@@ -160,19 +313,20 @@ function convertTypeAlias(node, source) {
         const allStringLiterals = members.every((m) => ts.isLiteralTypeNode(m) && m.literal.kind === ts.SyntaxKind.StringLiteral);
         if (allStringLiterals) {
             const values = members.map((m) => m.literal.text).join('|');
-            lines.push(`type name=${name} values="${values}"${exp}`);
+            lines.push(`type name=${name} values="${values}"${generics}${exp}`);
             return lines;
         }
     }
     // General type alias
     const typeText = typeToString(node.type, source);
-    lines.push(`type name=${name} alias="${escapeKernString(typeText)}"${exp}`);
+    lines.push(`type name=${name} alias="${escapeKernString(typeText)}"${generics}${exp}`);
     return lines;
 }
 function convertInterface(node, source) {
     const lines = [];
     const name = node.name.getText(source);
     const exp = isExported(node) ? ' export=true' : '';
+    const generics = genericsAttr(node.typeParameters, source);
     const doc = getJSDoc(node, source);
     if (doc)
         lines.push(`doc text="${escapeKernString(doc)}"`);
@@ -180,7 +334,7 @@ function convertInterface(node, source) {
         ?.filter((h) => h.token === ts.SyntaxKind.ExtendsKeyword)
         .flatMap((h) => h.types.map((t) => t.getText(source)));
     const extendsStr = extends_ && extends_.length > 0 ? ` extends=${extends_.join(',')}` : '';
-    lines.push(`interface name=${name}${extendsStr}${exp}`);
+    lines.push(`interface name=${name}${generics}${extendsStr}${exp}`);
     for (const member of node.members) {
         if (ts.isPropertySignature(member)) {
             const fieldName = member.name.getText(source);
@@ -196,10 +350,26 @@ function convertInterface(node, source) {
             const methodName = member.name.getText(source);
             const params = member.parameters ? formatParams(member.parameters, source) : '';
             const returns = typeToString(member.type, source) || 'void';
-            const funcType = `(${params}) => ${returns}`;
+            // Slice 2f — preserve method-level generics by prepending <T,...> to the function-type
+            // string when the method has typeParameters. Format: `<T>(params) => R`.
+            const tp = member.typeParameters;
+            const genericsBlock = tp && tp.length > 0 ? `<${tp.map((t) => t.getText(source)).join(', ')}>` : '';
+            const funcType = `${genericsBlock}(${params}) => ${returns}`;
             const optional = member.questionToken ? ' optional=true' : '';
             lines.push(`  field name=${methodName} type="${escapeKernString(funcType)}"${optional}`);
         }
+        else if (ts.isIndexSignatureDeclaration(member)) {
+            // [keyName: keyType]: type   →   indexer keyName=... keyType=... type=...
+            const param = member.parameters[0];
+            if (param) {
+                const keyName = param.name.getText(source);
+                const keyType = typeToString(param.type, source) || 'string';
+                const valueType = typeToString(member.type, source) || 'unknown';
+                const isReadonly = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.ReadonlyKeyword);
+                const ro = isReadonly ? ' readonly=true' : '';
+                lines.push(`  indexer keyName=${keyName} keyType=${keyType} type=${valueType}${ro}`);
+            }
+        }
     }
     return lines;
 }
@@ -207,19 +377,47 @@ function convertEnum(node, source) {
     const lines = [];
     const name = node.name.getText(source);
     const exp = isExported(node) ? ' export=true' : '';
+    const isConst = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ConstKeyword);
+    const constStr = isConst ? ' const=true' : '';
     const doc = getJSDoc(node, source);
     if (doc)
         lines.push(`doc text="${escapeKernString(doc)}"`);
-    // Check if all members are string literals → type with values
-    const allString = node.members.every((m) => m.initializer && ts.isStringLiteral(m.initializer));
-    if (allString) {
-        const values = node.members.map((m) => m.initializer.text).join('|');
-        lines.push(`type name=${name} values="${values}"${exp}`);
-    }
-    else {
-        // Numeric or mixed enum → type alias
+    // Auto-increment numeric enum: no explicit initializers → compact `values="A|B|C"` form.
+    const allBare = node.members.length > 0 && node.members.every((m) => !m.initializer);
+    if (allBare) {
         const values = node.members.map((m) => m.name.getText(source)).join('|');
-        lines.push(`type name=${name} values="${values}"${exp}`);
+        lines.push(`enum name=${name} values="${values}"${constStr}${exp}`);
+        return lines;
+    }
+    // Otherwise emit `member` children to preserve explicit values.
+    lines.push(`enum name=${name}${constStr}${exp}`);
+    for (const m of node.members) {
+        const mname = m.name.getText(source);
+        if (!m.initializer) {
+            lines.push(`  member name=${mname}`);
+        }
+        else if (ts.isStringLiteral(m.initializer)) {
+            const text = m.initializer.text;
+            if (text === '') {
+                // Empty string would be dropped by the codegen's "no value" guard
+                // (`if (rawVal === '') valueStr = ''`). Route via the expression
+                // form so it round-trips as the literal `""` instead of `Empty,`.
+                lines.push(`  member name=${mname} value={{""}}`);
+            }
+            else {
+                lines.push(`  member name=${mname} value="${escapeKernString(text)}"`);
+            }
+        }
+        else if (ts.isNumericLiteral(m.initializer)) {
+            lines.push(`  member name=${mname} value=${m.initializer.text}`);
+        }
+        else {
+            // Any other initializer (computed `1 << 2`, identifier reference, prefix
+            // unary like `-1`, etc.) — emit via {{expr}} so the codegen round-trips
+            // the raw expression instead of fabricating a string-quoted version.
+            const exprText = m.initializer.getText(source);
+            lines.push(`  member name=${mname} value={{${exprText}}}`);
+        }
     }
     return lines;
 }
@@ -227,19 +425,32 @@ function convertFunction(node, source) {
     const lines = [];
     const name = node.name?.getText(source) ?? 'anonymous';
     const exp = isExported(node) ? ' export=true' : '';
+    const generics = genericsAttr(node.typeParameters, source);
     const doc = getJSDoc(node, source);
     const asyncStr = isAsync(node) ? ' async=true' : '';
     const isGenerator = node.asteriskToken != null;
     const generatorStr = isGenerator ? (isAsync(node) ? ' stream=true' : ' generator=true') : '';
     if (doc)
         lines.push(`doc text="${escapeKernString(doc)}"`);
-    const params = formatParams(node.parameters, source);
+    // Slice 3c — prefer structured `param` child nodes when the signature is
+    // simple enough (no `?`/`...`/destructuring). Falls back to the legacy
+    // `params="..."` string for unsupported shapes.
+    const paramChildren = tryFormatParamChildren(node.parameters, source);
     const returns = typeToString(node.type, source);
-    const paramsStr = params ? ` params="${params}"` : '';
     const returnsStr = returns ? ` returns=${returns}` : '';
-    // For async generators, use stream=true instead of async=true + generator=true
     const asyncFinal = isGenerator && isAsync(node) ? '' : asyncStr;
-    lines.push(`fn name=${name}${paramsStr}${returnsStr}${asyncFinal}${generatorStr}${exp}`);
+    const paramsStr = paramChildren !== null
+        ? ''
+        : (() => {
+            const params = formatParams(node.parameters, source);
+            return params ? ` params="${params}"` : '';
+        })();
+    lines.push(`fn name=${name}${paramsStr}${returnsStr}${asyncFinal}${generatorStr}${generics}${exp}`);
+    if (paramChildren) {
+        for (const childLine of paramChildren) {
+            lines.push(`  ${childLine}`);
+        }
+    }
     const body = getBodyText(node.body, source);
     if (body) {
         lines.push('  handler <<<');
@@ -250,10 +461,46 @@ function convertFunction(node, source) {
     }
     return lines;
 }
+/** Slice 2e — convert a TS overload group (N signatures + 1 implementation)
+ *  to a single KERN `fn` node with `overload` children. The implementation is
+ *  the declaration that has a body; if none has a body (rare — ambient module
+ *  declarations), we treat the LAST as implementation for round-trip safety. */
+function convertFunctionGroup(group, source, stats) {
+    // Find the implementation (the one with a body). If none, fall back to last.
+    const implIdx = group.findIndex((fn) => fn.body != null);
+    const impl = group[implIdx >= 0 ? implIdx : group.length - 1];
+    const overloads = group.filter((fn) => fn !== impl);
+    // Convert the implementation as a normal function (fn). Then append overload children.
+    stats.functions++;
+    const implLines = convertFunction(impl, source);
+    // Insert overload child lines BEFORE the handler block (which lives under
+    // the `fn name=...` header line). We slice at the index of the handler open.
+    const overloadLines = [];
+    for (const ov of overloads) {
+        const params = formatParams(ov.parameters, source);
+        const returns = typeToString(ov.type, source);
+        const paramsStr = params ? ` params="${params}"` : '';
+        const returnsStr = returns ? ` returns=${returns}` : '';
+        // Slice 2f — overload signatures can declare their own type parameters
+        // (e.g. `function id<T>(x: T): T;` paired with non-generic impl).
+        // Without this, the overload would round-trip to invalid TS where T is undefined.
+        const generics = genericsAttr(ov.typeParameters, source);
+        overloadLines.push(`  overload${paramsStr}${returnsStr}${generics}`);
+    }
+    // Splice overload lines after the `fn name=...` (and its leading doc, if any)
+    // and before the `  handler <<<` block. We find the first line that starts
+    // with `  handler` (handler is the first child of fn) — overloads go before it.
+    const handlerIdx = implLines.findIndex((l) => l.startsWith('  handler'));
+    if (handlerIdx === -1) {
+        return [...implLines, ...overloadLines];
+    }
+    return [...implLines.slice(0, handlerIdx), ...overloadLines, ...implLines.slice(handlerIdx)];
+}
 function convertClass(node, source) {
     const lines = [];
     const name = node.name?.getText(source) ?? 'AnonymousClass';
     const exp = isExported(node) ? ' export=true' : '';
+    const generics = genericsAttr(node.typeParameters, source);
     const doc = getJSDoc(node, source);
     // Check if it extends Error → error node
     const extendsClause = node.heritageClauses?.find((h) => h.token === ts.SyntaxKind.ExtendsKeyword);
@@ -272,7 +519,7 @@ function convertClass(node, source) {
         : '';
     const extendsStr = extendsClause && !isError ? ` extends=${extendsClause.types.map((t) => t.getText(source)).join(',')}` : '';
     const abstractStr = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AbstractKeyword) ? ' abstract=true' : '';
-    lines.push(`class name=${name}${extendsStr}${implementsStr}${abstractStr}${exp}`);
+    lines.push(`class name=${name}${extendsStr}${implementsStr}${abstractStr}${generics}${exp}`);
     for (const member of node.members) {
         if (ts.isPropertyDeclaration(member)) {
             const fieldName = member.name.getText(source);
@@ -280,16 +527,33 @@ function convertClass(node, source) {
             const priv = isPrivate(member) ? ' private=true' : '';
             const ro = isReadonly(member) ? ' readonly=true' : '';
             const staticStr = isStatic(member) ? ' static=true' : '';
-            const defaultVal = member.initializer ? ` default={{ ${member.initializer.getText(source)} }}` : '';
+            // Slice 3b: emit `value={{ <init> }}` (canonical), not `default={{ ... }}`.
+            // The `{{...}}` wrap stays — TS initializers can be arbitrary expressions
+            // (function calls, ternaries, etc.) that ValueIR may not parse, and the
+            // ExprObject form is the safe escape hatch through emitConstValue.
+            const valueAttr = member.initializer ? ` value={{ ${member.initializer.getText(source)} }}` : '';
             const memberDoc = getJSDoc(member, source);
             if (memberDoc)
                 lines.push(`  doc text="${escapeKernString(memberDoc)}"`);
-            lines.push(`  field name=${fieldName}${fieldType ? ` type=${fieldType}` : ''}${priv}${staticStr}${ro}${defaultVal}`);
+            lines.push(`  field name=${fieldName}${fieldType ? ` type=${fieldType}` : ''}${priv}${staticStr}${ro}${valueAttr}`);
         }
         else if (ts.isConstructorDeclaration(member)) {
-            const ctorParams = formatParams(member.parameters, source);
-            const ctorParamsStr = ctorParams ? ` params="${ctorParams}"` : '';
-            lines.push(`  constructor${ctorParamsStr}`);
+            // Slice 3c — try structured `param` children for default-bearing
+            // signatures; fall back to legacy `params="..."` string otherwise.
+            const ctorParamChildren = tryFormatParamChildren(member.parameters, source);
+            const ctorParamsStr = ctorParamChildren !== null
+                ? ''
+                : (() => {
+                    const ctorParams = formatParams(member.parameters, source);
+                    return ctorParams ? ` params="${ctorParams}"` : '';
+                })();
+            const generics = genericsAttr(member.typeParameters, source);
+            lines.push(`  constructor${ctorParamsStr}${generics}`);
+            if (ctorParamChildren) {
+                for (const childLine of ctorParamChildren) {
+                    lines.push(`    ${childLine}`);
+                }
+            }
             const body = getBodyText(member.body, source);
             if (body) {
                 lines.push('    handler <<<');
@@ -301,17 +565,28 @@ function convertClass(node, source) {
         }
         else if (ts.isMethodDeclaration(member)) {
             const methodName = member.name.getText(source);
-            const params = formatParams(member.parameters, source);
+            const paramChildren = tryFormatParamChildren(member.parameters, source);
             const returns = typeToString(member.type, source);
+            const generics = genericsAttr(member.typeParameters, source);
             const asyncStr = isAsync(member) ? ' async=true' : '';
             const staticStr = isStatic(member) ? ' static=true' : '';
             const privStr = isPrivate(member) ? ' private=true' : '';
-            const paramsStr = params ? ` params="${params}"` : '';
+            const paramsStr = paramChildren !== null
+                ? ''
+                : (() => {
+                    const params = formatParams(member.parameters, source);
+                    return params ? ` params="${params}"` : '';
+                })();
             const returnsStr = returns ? ` returns=${returns}` : '';
             const memberDoc = getJSDoc(member, source);
             if (memberDoc)
                 lines.push(`  doc text="${escapeKernString(memberDoc)}"`);
-            lines.push(`  method name=${methodName}${paramsStr}${returnsStr}${asyncStr}${staticStr}${privStr}`);
+            lines.push(`  method name=${methodName}${paramsStr}${returnsStr}${asyncStr}${staticStr}${privStr}${generics}`);
+            if (paramChildren) {
+                for (const childLine of paramChildren) {
+                    lines.push(`    ${childLine}`);
+                }
+            }
             const body = getBodyText(member.body, source);
             if (body) {
                 lines.push('    handler <<<');
@@ -338,11 +613,21 @@ function convertClass(node, source) {
         }
         else if (ts.isSetAccessorDeclaration(member)) {
             const sname = member.name.getText(source);
-            const params = formatParams(member.parameters, source);
-            const paramsStr = params ? ` params="${params}"` : '';
+            const setterParamChildren = tryFormatParamChildren(member.parameters, source);
+            const paramsStr = setterParamChildren !== null
+                ? ''
+                : (() => {
+                    const params = formatParams(member.parameters, source);
+                    return params ? ` params="${params}"` : '';
+                })();
             const privStr = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword) ? ' private=true' : '';
             const staticStr = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword) ? ' static=true' : '';
             lines.push(`  setter name=${sname}${paramsStr}${privStr}${staticStr}`);
+            if (setterParamChildren) {
+                for (const childLine of setterParamChildren) {
+                    lines.push(`    ${childLine}`);
+                }
+            }
             const body = getBodyText(member.body, source);
             if (body) {
                 lines.push('    handler <<<');
@@ -386,11 +671,223 @@ function convertErrorClass(node, source, name, baseClass, exp, lines) {
     }
     return lines;
 }
+/**
+ * Slice 3d — try to format a destructured `const`/`let` declaration as a
+ * structured `destructure` IR node with `binding` (object) or `element`
+ * (array) children. Returns `null` for non-destructured patterns; returns
+ * a single fallback line carrying the raw statement in `expr={{...}}` for
+ * patterns we can't structure (rest `...`, defaults `=v`, nested `{a:{b}}`,
+ * computed/string keys).
+ */
+function tryFormatDestructure(decl, kind, exported, source, fullStmtText) {
+    if (!decl.initializer)
+        return null;
+    const isObj = ts.isObjectBindingPattern(decl.name);
+    const isArr = ts.isArrayBindingPattern(decl.name);
+    if (!isObj && !isArr)
+        return null;
+    const fallback = () => [`destructure expr={{ ${fullStmtText} }}`];
+    const childLines = [];
+    if (isObj) {
+        for (const el of decl.name.elements) {
+            if (el.dotDotDotToken)
+                return fallback();
+            if (el.initializer)
+                return fallback();
+            if (!ts.isIdentifier(el.name))
+                return fallback();
+            const localName = el.name.getText(source);
+            let line = `binding name=${localName}`;
+            if (el.propertyName) {
+                if (!ts.isIdentifier(el.propertyName))
+                    return fallback();
+                line += ` key=${el.propertyName.getText(source)}`;
+            }
+            childLines.push(line);
+        }
+    }
+    else {
+        let idx = 0;
+        for (const el of decl.name.elements) {
+            if (ts.isOmittedExpression(el)) {
+                idx++;
+                continue;
+            }
+            if (el.dotDotDotToken)
+                return fallback();
+            if (el.initializer)
+                return fallback();
+            if (!ts.isIdentifier(el.name))
+                return fallback();
+            childLines.push(`element name=${el.name.getText(source)} index=${idx}`);
+            idx++;
+        }
+    }
+    if (childLines.length === 0)
+        return fallback();
+    const sourceText = decl.initializer.getText(source);
+    const isSimpleIdent = /^[A-Za-z_$][\w$]*$/.test(sourceText);
+    const sourceAttr = isSimpleIdent ? ` source=${sourceText}` : ` source={{ ${sourceText} }}`;
+    const type = typeToString(decl.type, source);
+    const typeAttr = type ? ` type=${type}` : '';
+    const expAttr = exported ? ' export=true' : '';
+    const lines = [`destructure kind=${kind}${typeAttr}${sourceAttr}${expAttr}`];
+    for (const line of childLines)
+        lines.push(`  ${line}`);
+    return lines;
+}
+/**
+ * Slice 3e — pick the right KERN attribute form for a TS expression node
+ * used as a key/value in a Map/Set literal entry.
+ *
+ *   - String literals → `prop="foo"` so the quoted source flows through
+ *     __quotedProps and codegen JSON-stringifies.
+ *   - Primitive literals (numeric, true, false, null) → `prop=42` bare so
+ *     they go through ValueIR canonicalisation per slice 3a-c precedent.
+ *   - Anything else → `prop={{ raw-ts }}` ExprObject escape hatch.
+ */
+function formatLitEntryAttr(propName, expr, source) {
+    const text = expr.getText(source);
+    if (ts.isStringLiteral(expr))
+        return `${propName}=${text}`;
+    if (ts.isNumericLiteral(expr) ||
+        expr.kind === ts.SyntaxKind.TrueKeyword ||
+        expr.kind === ts.SyntaxKind.FalseKeyword ||
+        expr.kind === ts.SyntaxKind.NullKeyword) {
+        return `${propName}=${text}`;
+    }
+    return `${propName}={{ ${text} }}`;
+}
+/**
+ * Slice 3e — try to format `const x = new Map([['k', v], ...])` as a
+ * structured `mapLit` IR node with `mapEntry` children. Returns null when
+ * the initializer is not a Map constructor call, or when the array argument
+ * contains non-canonical entries (spread, computed keys, non-tuple entries).
+ */
+function tryFormatMapLit(decl, kind, exported, source) {
+    if (!decl.initializer || !ts.isNewExpression(decl.initializer))
+        return null;
+    if (decl.initializer.expression.getText(source) !== 'Map')
+        return null;
+    if (!ts.isIdentifier(decl.name))
+        return null;
+    // Empty `new Map()` or unusual form — pass through.
+    const args = decl.initializer.arguments;
+    if (!args || args.length === 0)
+        return null;
+    const arg = args[0];
+    if (!ts.isArrayLiteralExpression(arg))
+        return null;
+    const entryLines = [];
+    for (const el of arg.elements) {
+        if (!ts.isArrayLiteralExpression(el))
+            return null; // non-tuple entry
+        if (el.elements.length !== 2)
+            return null; // not [k, v]
+        if (el.elements.some((e) => ts.isSpreadElement(e)))
+            return null;
+        const keyAttr = formatLitEntryAttr('key', el.elements[0], source);
+        const valAttr = formatLitEntryAttr('value', el.elements[1], source);
+        entryLines.push(`mapEntry ${keyAttr} ${valAttr}`);
+    }
+    if (entryLines.length === 0)
+        return null; // empty array — pass through
+    const name = decl.name.getText(source);
+    const type = typeToString(decl.type, source);
+    const typeAttr = type ? ` type=${type}` : '';
+    const expAttr = exported ? ' export=true' : '';
+    const kindAttr = kind === 'let' ? ' kind=let' : '';
+    const lines = [`mapLit name=${name}${typeAttr}${kindAttr}${expAttr}`];
+    for (const l of entryLines)
+        lines.push(`  ${l}`);
+    return lines;
+}
+/**
+ * Slice 3e — try to format `const x = new Set([v1, v2, ...])` as a
+ * structured `setLit` IR node with `setItem` children. Returns null when
+ * the initializer is not a Set constructor call, or when the array argument
+ * contains non-canonical members (spread).
+ */
+function tryFormatSetLit(decl, kind, exported, source) {
+    if (!decl.initializer || !ts.isNewExpression(decl.initializer))
+        return null;
+    if (decl.initializer.expression.getText(source) !== 'Set')
+        return null;
+    if (!ts.isIdentifier(decl.name))
+        return null;
+    const args = decl.initializer.arguments;
+    if (!args || args.length === 0)
+        return null;
+    const arg = args[0];
+    if (!ts.isArrayLiteralExpression(arg))
+        return null;
+    const itemLines = [];
+    for (const el of arg.elements) {
+        if (ts.isSpreadElement(el))
+            return null;
+        itemLines.push(`setItem ${formatLitEntryAttr('value', el, source)}`);
+    }
+    if (itemLines.length === 0)
+        return null;
+    const name = decl.name.getText(source);
+    const type = typeToString(decl.type, source);
+    const typeAttr = type ? ` type=${type}` : '';
+    const expAttr = exported ? ' export=true' : '';
+    const kindAttr = kind === 'let' ? ' kind=let' : '';
+    const lines = [`setLit name=${name}${typeAttr}${kindAttr}${expAttr}`];
+    for (const l of itemLines)
+        lines.push(`  ${l}`);
+    return lines;
+}
 function convertVariableStatement(node, source) {
     const lines = [];
     const exp = isExported(node) ? ' export=true' : '';
     const doc = getJSDoc(node, source);
+    // Slice 3d — derive const|let|var from the declaration list flags.
+    const declKind = (node.declarationList.flags & ts.NodeFlags.Const) !== 0
+        ? 'const'
+        : (node.declarationList.flags & ts.NodeFlags.Let) !== 0
+            ? 'let'
+            : 'const';
     for (const decl of node.declarationList.declarations) {
+        // Slice 3d — destructured LHS handled BEFORE the simple-value branch
+        // because `decl.name` for `const {a,b}=obj` is a binding pattern, not
+        // an identifier. Falls through to the legacy paths only when LHS is a
+        // plain identifier.
+        if (ts.isObjectBindingPattern(decl.name) || ts.isArrayBindingPattern(decl.name)) {
+            if (doc)
+                lines.push(`doc text="${escapeKernString(doc)}"`);
+            // Reconstruct the full statement text for the expr= fallback path.
+            // Prefer node.getText(source) so we capture `export const {a}=obj;` shape.
+            const fullStmtText = node.getText(source).trim().replace(/;$/, '');
+            const result = tryFormatDestructure(decl, declKind, isExported(node), source, fullStmtText);
+            if (result) {
+                for (const l of result)
+                    lines.push(l);
+                continue;
+            }
+        }
+        // Slice 3e — Map/Set literal detection. Falls through to legacy const
+        // when the constructor argument shape isn't structurable (spread,
+        // computed keys, non-tuple entries, etc.).
+        {
+            const mapLines = tryFormatMapLit(decl, declKind, isExported(node), source);
+            if (mapLines) {
+                if (doc)
+                    lines.push(`doc text="${escapeKernString(doc)}"`);
+                for (const l of mapLines)
+                    lines.push(l);
+                continue;
+            }
+            const setLines = tryFormatSetLit(decl, declKind, isExported(node), source);
+            if (setLines) {
+                if (doc)
+                    lines.push(`doc text="${escapeKernString(doc)}"`);
+                for (const l of setLines)
+                    lines.push(l);
+                continue;
+            }
+        }
         const name = decl.name.getText(source);
         const type = typeToString(decl.type, source);
         const typeStr = type ? ` type=${type}` : '';
@@ -419,14 +916,27 @@ function convertVariableStatement(node, source) {
                 // Arrow function or function expression → fn
                 const func = decl.initializer;
                 const asyncStr = isAsync(func) ? ' async=true' : '';
-                const params = formatParams(func.parameters, source);
+                // Slice 3c — try structured `param` children for default-bearing
+                // signatures; fall back to legacy `params="..."` string otherwise.
+                const paramChildren = tryFormatParamChildren(func.parameters, source);
                 const returns = typeToString(func.type, source);
-                const paramsStr = params ? ` params="${params}"` : '';
+                const generics = genericsAttr(func.typeParameters, source);
+                const paramsStr = paramChildren !== null
+                    ? ''
+                    : (() => {
+                        const params = formatParams(func.parameters, source);
+                        return params ? ` params="${params}"` : '';
+                    })();
                 const returnsStr = returns ? ` returns=${returns}` : '';
                 const isGen = ts.isFunctionExpression(func) && func.asteriskToken != null;
                 const genStr = isGen ? (isAsync(func) ? ' stream=true' : ' generator=true') : '';
                 const asyncFinal = isGen && isAsync(func) ? '' : asyncStr;
-                lines.push(`fn name=${name}${paramsStr}${returnsStr}${asyncFinal}${genStr}${exp}`);
+                lines.push(`fn name=${name}${paramsStr}${returnsStr}${asyncFinal}${genStr}${generics}${exp}`);
+                if (paramChildren) {
+                    for (const childLine of paramChildren) {
+                        lines.push(`  ${childLine}`);
+                    }
+                }
                 const body = ts.isArrowFunction(func)
                     ? getBodyText(func.body, source)
                     : getBodyText(func.body, source);
@@ -1084,7 +1594,37 @@ export function importTypeScript(tsSource, fileName = 'input.ts') {
         enums: 0,
         components: 0,
     };
-    for (const statement of sourceFile.statements) {
+    // Slice 2e — TS overloaded functions are a sequence of FunctionDeclaration
+    // nodes sharing a name, where the LAST one has a body and the earlier ones
+    // are signature-only. Group them so the importer emits a single `fn` with
+    // `overload` children rather than N separate fn nodes.
+    const statements = sourceFile.statements;
+    for (let i = 0; i < statements.length; i++) {
+        const statement = statements[i];
+        if (ts.isFunctionDeclaration(statement) && statement.name) {
+            const fnName = statement.name.getText(sourceFile);
+            // Look ahead to collect consecutive same-named function declarations.
+            const group = [statement];
+            while (i + 1 < statements.length) {
+                const next = statements[i + 1];
+                if (ts.isFunctionDeclaration(next) && next.name && next.name.getText(sourceFile) === fnName) {
+                    group.push(next);
+                    i++;
+                }
+                else {
+                    break;
+                }
+            }
+            if (group.length > 1) {
+                const converted = convertFunctionGroup(group, sourceFile, stats);
+                if (converted.length > 0) {
+                    kernLines.push(...converted);
+                    kernLines.push('');
+                }
+                continue;
+            }
+            // Single declaration — fall through to ordinary path.
+        }
         const converted = convertStatement(statement, sourceFile, unmapped, stats);
         if (converted.length > 0) {
             kernLines.push(...converted);