depyo 1.0.2 → 1.1.0

package/lib/PycDecompiler.js

@@ -1,6 +1,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const AST = require('./ast/ast_node');
+const { resolveBoolChainFrames } = require('./handlers/control_flow_jumps');
 
 Array.prototype.top = function ArrayTop (pos = 0) {
     return this[this.length - pos - 1];
@@ -13,6 +14,7 @@ Array.prototype.empty = function ArrayIsEmpty () {
 class PycDecompiler {
     static opCodeHandlers = {};
     cleanBuild = false;
+    errors = [];               // Per-opcode exceptions caught by main loop. Non-empty → cleanBuild=false.
     object = null;
     code = null;
 
@@ -97,21 +99,32 @@ class PycDecompiler {
                                 typeof fileExports[handlerName] === 'function' &&
                                 handlerName.startsWith("handle")) {
     
-                                // Convert handler name (e.g., "handleJumpForwardA") to opcode name ("JUMP_FORWARD_A")
-                                let opCodeName = handlerName.replace(/^handle/, '')
-                                                .replaceAll(/([A-Z][a-z]+)/g, m => m.toUpperCase() + '_')
-                                                .replace(/_$/, '');
+                                // Convert handler name (e.g., "handleJumpForwardA") to opcode name ("JUMP_FORWARD_A").
+                                // Primary rule: camelCase → SNAKE_CASE with explicit runs-of-caps handling
+                                // (HandleABCDef → ABC_DEF). Some legacy handlers like handleCallIntrinsic1A
+                                // still map via the looser regex — OpCodes.js provides both _1A and _1_A aliases.
+                                const body = handlerName.replace(/^handle/, '');
+                                let opCodeName = body
+                                    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+                                    .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+                                    .toUpperCase();
+                                if (!(opCodeName in OpCodesMap)) {
+                                    const legacy = body
+                                        .replaceAll(/([A-Z][a-z]+)/g, m => m.toUpperCase() + '_')
+                                        .replace(/_$/, '');
+                                    if (legacy in OpCodesMap) opCodeName = legacy;
+                                }
     
                                 if (opCodeName in OpCodesMap) {
                                     const opCodeId = OpCodesMap[opCodeName];
                                     const handlerFunc = fileExports[handlerName];
     
                                     if (PycDecompiler.opCodeHandlers[opCodeId]) {
-                                         console.warn(`Static Handler warning: OpCode ${opCodeName} (${opCodeId}) already has a handler. Overwriting.`);
+                                        throw new Error(`Static handler collision: OpCode ${opCodeName} (${opCodeId}) already bound; refusing silent overwrite from ${entry.name}:${handlerName}.`);
                                     }
                                     PycDecompiler.opCodeHandlers[opCodeId] = handlerFunc;
                                 } else {
-                                    console.warn(`Static Handler mapping warning: OpCode name "${opCodeName}" from ${entry.name} not found in OpCodes map.`);
+                                    throw new Error(`Static handler mapping failed: "${opCodeName}" (from ${entry.name}:${handlerName}) is not in OpCodes. Rename the handler to match a known opcode, or add the opcode to lib/OpCodes.js.`);
                                 }
                             }
                         }
@@ -137,9 +150,15 @@ class PycDecompiler {
         this.enrichGenericAnnotations(functonBody);
         this.rewriteClassDefinitions(functonBody);
         this.removeNullSentinelComparisons(functonBody);
+        this.cleanupExcMatchArtifacts(functonBody);
+        this.hoistNestedExceptBlocks(functonBody);
         this.dedupeExceptHandlers(functonBody);
         this.removeDuplicateReturns(functonBody);
 
+        if (this.object.Name == "<lambda>") {
+            this.foldLambdaConditional(functonBody);
+        }
+
         if (this.object.Name != "<lambda>" && functonBody.last instanceof AST.ASTReturn && functonBody.last.value instanceof AST.ASTNone) {
             functonBody.list.pop();
         }
@@ -152,6 +171,81 @@ class PycDecompiler {
         return functonBody;
     }
 
+    foldLambdaConditional(body) {
+        // Lambda bodies must be single expressions. CPython often compiles a
+        // conditional expression `A if cond else B` as:
+        //   POP_JUMP_IF_FALSE X; LOAD A; RETURN_VALUE; X: LOAD B; RETURN_VALUE
+        // The decompiler's default path leaves this as two statements which is
+        // invalid Python inside a lambda. Detect the patterns and fold into a
+        // single ASTReturn(ASTTernary).
+        const list = body?.list;
+        if (!Array.isArray(list) || list.length !== 2) {
+            return;
+        }
+        const first = list[0];
+        const second = list[1];
+        if (!(second instanceof AST.ASTReturn)) {
+            return;
+        }
+        const elseVal = second.value;
+
+        const makeCondBlock = (condExpr, negative) => {
+            const cb = new AST.ASTCondBlock(AST.ASTBlock.BlockType.If, 0, 0, condExpr, !!negative);
+            return cb;
+        };
+
+        let tern = null;
+
+        // Case 1: first is `ASTReturn(ASTBinary(cond AND/OR val))` — the line-900
+        // collapse already ran. Recover cond/val/direction from the binary op.
+        if (first instanceof AST.ASTReturn && first.value instanceof AST.ASTBinary) {
+            const bin = first.value;
+            const isAnd = bin.op === AST.ASTBinary.BinOp.LogicalAnd;
+            const isOr = bin.op === AST.ASTBinary.BinOp.LogicalOr;
+            if (isAnd || isOr) {
+                const cond = bin.left;
+                const thenVal = bin.right;
+                const cb = makeCondBlock(cond, isOr);
+                tern = new AST.ASTTernary(cb, thenVal, elseVal);
+            }
+        }
+
+        // Case 2: first is an ASTCondBlock (if-return not collapsed by line 900).
+        if (!tern && first instanceof AST.ASTCondBlock &&
+            first.blockType === AST.ASTBlock.BlockType.If &&
+            Array.isArray(first.nodes) && first.nodes.length === 1 &&
+            first.nodes[0] instanceof AST.ASTReturn) {
+            const thenVal = first.nodes[0].value;
+            const cb = makeCondBlock(first.condition, first.negative);
+            tern = new AST.ASTTernary(cb, thenVal, elseVal);
+        }
+
+        if (!tern) {
+            // Two plain-return statements with no folded condition = optimizer
+            // eliminated the `if X else Y` when X was a constant, or the first
+            // return short-circuits the whole lambda (e.g. chained compare).
+            // The second return is unreachable; drop it so the lambda renders
+            // as a valid expression. Also covers generator lambdas where the
+            // yield expression is followed by the implicit `return None`.
+            const secondIsImplicitNone =
+                second instanceof AST.ASTReturn &&
+                second.rettype === AST.ASTReturn.RetType.Return &&
+                (!second.value || second.value instanceof AST.ASTNone);
+            if (first instanceof AST.ASTReturn &&
+                (first.rettype === AST.ASTReturn.RetType.Return || secondIsImplicitNone)) {
+                body.list.length = 1;
+                first.inLambda = true;
+            }
+            return;
+        }
+
+        const folded = new AST.ASTReturn(tern);
+        folded.inLambda = true;
+        folded.line = second.line ?? first.line;
+        body.list.length = 0;
+        body.list.push(folded);
+    }
+
     append_to_chain_store(chainStore, item)
     {
         if (this.dataStack.top() == item) {
@@ -243,6 +337,23 @@ class PycDecompiler {
         if (!(rit instanceof AST.ASTBlock) ||
             rit.blockType != AST.ASTBlock.BlockType.If)
             return;
+        // Peek before mutating: a real ternary needs both branches as expressions
+        // on the data stack. Otherwise the if/else are real statements (the bytecode
+        // path covers a control-flow if, not an if-expr) and rewriting them produces
+        // a ##ERROR## ternary that masks the real source.
+        const else_candidate = this.dataStack.top();
+        if (else_candidate == null) {
+            return;
+        }
+        const ifBlockCandidate = this.curBlock.nodes[this.curBlock.nodes.length - 2];
+        const stackDepth = this.dataStack.length;
+        const ifExprOnStack = stackDepth >= 2 ? this.dataStack[stackDepth - 2] : null;
+        const ifExprFromBody = ifExprOnStack == null && ifBlockCandidate.nodes.length == 1
+            ? ifBlockCandidate.nodes[0]
+            : ifExprOnStack;
+        if (ifExprFromBody == null) {
+            return;
+        }
         let else_expr = this.dataStack.pop();
         this.curBlock.removeLast();
         let if_block = this.curBlock.nodes.top();
@@ -319,7 +430,19 @@ class PycDecompiler {
         if (offset === undefined) {
             return;
         }
-        const maxHandlerEnd = this.maxExceptionHandlerEnd || Math.max(...entries.filter(e => e.depth > 0).map(e => e.end || 0), 0);
+        // Exclude cleanup-only handler entries (depth>0 whose start is a RERAISE site,
+        // not a PUSH_EXC_INFO) from the try-block span. Those entries protect CPython's
+        // implicit re-raise tail, not a user-written except, and must not be treated
+        // as handler bodies when sizing the enclosing try.
+        const isUserHandlerEntry = (e) => {
+            if (!e || e.depth <= 0) return false;
+            const startInstr = this.code.PeekInstructionAtOffset(e.start);
+            return startInstr && startInstr.OpCodeID === this.OpCodes.PUSH_EXC_INFO;
+        };
+        const maxHandlerEnd = this.maxExceptionHandlerEnd || Math.max(
+            ...entries.filter(e => e.depth > 0 && isUserHandlerEntry(e)).map(e => e.end || 0),
+            0
+        );
 
         // Build set of WITH_EXCEPT_START handler ranges (lazily, once per code object)
         if (!this._withExceptRanges) {
@@ -470,6 +593,16 @@ class PycDecompiler {
                     }
                 }
             }
+            // Skip depth>0 entries whose start is a RERAISE cleanup site rather than
+            // a user-level PUSH_EXC_INFO handler. These appear in CPython 3.11+ as
+            // protected tails around `RERAISE 0` or `COPY n; POP_EXCEPT; RERAISE 1`
+            // and have no source-level except counterpart.
+            if (entry.depth > 0 && !isUserHandlerEntry(entry)) {
+                if (g_cliArgs?.debug) {
+                    console.log(`[EnsureExcBlocks] Skipping cleanup-only handler entry at ${entry.start} (not PUSH_EXC_INFO)`);
+                }
+                continue;
+            }
             const handlerEnd = entry.depth === 0
                 ? (maxHandlerEnd || entry.end || this.code.LastOffset || this.object.CodeSize || 0)
                 : (entry.end || maxHandlerEnd || this.code.LastOffset || this.object.CodeSize || 0);
@@ -520,7 +653,70 @@ class PycDecompiler {
         if (!matches.length) {
             return this.maxExceptionHandlerEnd || null;
         }
-        return Math.max(...matches.map(e => e.end));
+        let end = Math.max(...matches.map(e => e.end));
+        // CPython 3.11+ splits a single source-level except handler into
+        // contiguous depth>0 sub-regions (alias-binding, body, cleanup).
+        // Walk forward through adjacent depth>0 entries so the Except block
+        // covers the full handler body, not just the alias-binding region.
+        let guard = 0;
+        while (guard++ < 32) {
+            const next = entries.find(e =>
+                e.depth > 0 &&
+                e.start >= end &&
+                e.start <= end + 2 &&
+                e.end > end);
+            if (!next) break;
+            end = next.end;
+        }
+        // The exception-table entry only covers the prologue (the protected
+        // region around CHECK_EXC_MATCH). The actual handler body — user
+        // statements, POP_EXCEPT, and the terminating exit — lives past the
+        // entry end. Walk forward to include POP_EXCEPT and the following
+        // terminator (RETURN/JUMP_FORWARD/RERAISE) so the Except block
+        // captures the body that renders as user code.
+        if (this.code && this.OpCodes) {
+            let cursor = end;
+            let steps = 0;
+            let sawHandlerExit = false;
+            while (cursor >= 0 && steps++ < 500) {
+                const instr = this.code.PeekInstructionAtOffset(cursor);
+                if (!instr) break;
+                const op = instr.OpCodeID;
+                // Stop if we enter another handler's prologue.
+                if (op === this.OpCodes.PUSH_EXC_INFO) break;
+                if (op === this.OpCodes.POP_EXCEPT) {
+                    sawHandlerExit = true;
+                    end = instr.Offset + (instr.Size || 2);
+                    cursor = end;
+                    continue;
+                }
+                if (sawHandlerExit && (
+                    op === this.OpCodes.RETURN_VALUE ||
+                    op === this.OpCodes.RETURN_VALUE_A ||
+                    op === this.OpCodes.RETURN_CONST_A ||
+                    op === this.OpCodes.JUMP_FORWARD ||
+                    op === this.OpCodes.JUMP_FORWARD_A ||
+                    op === this.OpCodes.JUMP_BACKWARD ||
+                    op === this.OpCodes.JUMP_BACKWARD_A ||
+                    op === this.OpCodes.RERAISE ||
+                    op === this.OpCodes.RERAISE_A)) {
+                    end = instr.Offset + (instr.Size || 2);
+                    break;
+                }
+                if (sawHandlerExit) {
+                    // Skip trailing CACHE/POP_TOP cleanup that sometimes sits
+                    // between POP_EXCEPT and the terminator on 3.11+.
+                    if (op === this.OpCodes.CACHE ||
+                        op === this.OpCodes.POP_TOP) {
+                        cursor = instr.Offset + (instr.Size || 2);
+                        continue;
+                    }
+                    break;
+                }
+                cursor = instr.Offset + (instr.Size || 2);
+            }
+        }
+        return end;
     }
     
     statements () {
@@ -538,6 +734,83 @@ class PycDecompiler {
                 // Open blocks based on 3.11+ exception table (no SETUP_EXCEPT opcodes)
                 this.ensureExceptionTableBlocks();
 
+                // Early-return/raise in try body: CPython omits POP_BLOCK+JUMP_FORWARD,
+                // so the Try block is still open when we reach the except/finally handler.
+                // Close it and open Except/Finally here so handler prologue is consumed
+                // in the right block and __exception__ doesn't leak into Try.
+                if (this.code.Current.Offset > 0 && this.blocks.length > 1) {
+                    let tryIdx = -1, containerIdx = -1, isFinally = false;
+                    for (let i = this.blocks.length - 1; i >= 0; i--) {
+                        const blk = this.blocks[i];
+                        if (blk.blockType === AST.ASTBlock.BlockType.Container) {
+                            if (blk.hasExcept && blk.except === this.code.Current.Offset) {
+                                containerIdx = i;
+                                isFinally = false;
+                                break;
+                            }
+                            if (blk.hasFinally && !blk.hasExcept
+                                && blk.finally === this.code.Current.Offset) {
+                                containerIdx = i;
+                                isFinally = true;
+                                break;
+                            }
+                        }
+                        if (blk.blockType === AST.ASTBlock.BlockType.Try && tryIdx === -1) {
+                            tryIdx = i;
+                        }
+                    }
+                    if (containerIdx >= 0 && tryIdx > containerIdx
+                        && this.curBlock.blockType !== AST.ASTBlock.BlockType.Except
+                        && this.curBlock.blockType !== AST.ASTBlock.BlockType.Finally) {
+                        while (this.blocks.length - 1 > containerIdx) {
+                            const top = this.blocks[this.blocks.length - 1];
+                            this.blocks.pop();
+                            this.curBlock = this.blocks.top();
+                            this.curBlock.append(top);
+                        }
+                        const cont = this.curBlock;
+                        const handlerStart = isFinally ? cont.finally : cont.except;
+                        let handlerEnd = handlerStart;
+                        let cursor = handlerStart;
+                        for (let k = 0; k < 500; k++) {
+                            const instr = this.code.PeekInstructionAtOffset(cursor);
+                            if (!instr) break;
+                            const op = instr.OpCodeID;
+                            if (op === this.OpCodes.END_FINALLY
+                                || op === this.OpCodes.POP_EXCEPT
+                                || op === this.OpCodes.RERAISE_A
+                                || op === this.OpCodes.RERAISE) {
+                                handlerEnd = instr.Offset;
+                                break;
+                            }
+                            if (op === this.OpCodes.RETURN_VALUE
+                                || op === this.OpCodes.RETURN_VALUE_A
+                                || op === this.OpCodes.RETURN_CONST_A
+                                || op === this.OpCodes.RAISE_VARARGS_A) {
+                                handlerEnd = instr.Offset + (instr.Size || 2);
+                                break;
+                            }
+                            cursor = instr.Offset + (instr.Size || 2);
+                        }
+                        if (isFinally) {
+                            let finallyBlk = new AST.ASTBlock(AST.ASTBlock.BlockType.Finally, this.code.Current.Offset, handlerEnd, true);
+                            this.blocks.push(finallyBlk);
+                            this.curBlock = this.blocks.top();
+                            if (global.g_cliArgs?.debug) {
+                                console.log(`[EarlyReturnFinally] Opened Finally at ${this.code.Current.Offset}, handlerEnd=${handlerEnd}`);
+                            }
+                        } else {
+                            let except = new AST.ASTCondBlock(AST.ASTBlock.BlockType.Except, this.code.Current.Offset, handlerEnd, null, false);
+                            except.init();
+                            this.blocks.push(except);
+                            this.curBlock = this.blocks.top();
+                            if (global.g_cliArgs?.debug) {
+                                console.log(`[EarlyReturnExcept] Opened Except at ${this.code.Current.Offset}, handlerEnd=${handlerEnd}`);
+                            }
+                        }
+                    }
+                }
+
                 // Python 3.8: When entering exception handler, push exception instance to stack
                 if (this.exceptionHandlerOffsets.has(this.code.Current.Offset)) {
                     // Create synthetic exception instance placeholder
@@ -708,10 +981,33 @@ class PycDecompiler {
                     }
                 }
 
+                // Resolve any open boolean-expression chain frames whose target
+                // offset matches the current instruction. This folds pending
+                // JUMP_IF_FALSE/TRUE lhs+rhs pairs into ASTBinary AND/OR nodes
+                // and pushes the result onto dataStack before the consumer
+                // (STORE_*, RETURN_*, CALL_*, or a nested JUMP_IF_*) fires.
+                if (this.boolChainStack && this.boolChainStack.length > 0) {
+                    resolveBoolChainFrames(this, this.code.Current.Offset);
+                }
+
                 if (this.code.Current.OpCodeID in PycDecompiler.opCodeHandlers)
                 {
                     PycDecompiler.opCodeHandlers[this.code.Current.OpCodeID].call(this);
                 } else {
+                    // Unsupported opcode: bail out of the loop with what we have.
+                    // Record so `--strict` and the dirty-files report can surface it.
+                    this.errors.push({
+                        opcode: this.code.Current.InstructionName,
+                        argument: this.code.Current.Argument,
+                        offset: this.code.Current.Offset,
+                        fileOffset: this.object.codeOffset + this.code.Current.Offset,
+                        codeObject: this.object.Name,
+                        message: `Unsupported opcode ${this.code.Current.InstructionName}`,
+                        unsupported: true
+                    });
+                    if (global.g_cliArgs?.strict) {
+                        throw new Error(`Unsupported opcode ${this.code.Current.InstructionName} at offset ${this.code.Current.Offset}`);
+                    }
                     if (!g_cliArgs?.silent) {
                         console.error(`Unsupported opcode ${this.code.Current.InstructionName} at pos ${this.code.Current.Offset}\n`);
                     }
@@ -727,6 +1023,21 @@ class PycDecompiler {
                         && (this.curBlock.end == this.code.Next?.Offset);
 
             } catch (ex) {
+                // Record the failure so callers can detect partial output. Without this
+                // accumulator the main loop swallows handler exceptions silently and
+                // cleanBuild gets reset to true at end-of-loop, masking corruption.
+                this.errors.push({
+                    opcode: this.code.Current.InstructionName,
+                    argument: this.code.Current.Argument,
+                    offset: this.code.Current.Offset,
+                    fileOffset: this.object.codeOffset + this.code.Current.Offset,
+                    codeObject: this.object.Name,
+                    message: ex.message,
+                    stack: ex.stack
+                });
+                if (global.g_cliArgs?.strict) {
+                    throw ex;
+                }
                 if (!g_cliArgs?.silent) {
                     console.error(`EXCEPTION for OpCode ${this.code.Current.InstructionName} (${this.code.Current.Argument}) at offset ${this.code.Current.Offset} in code object '${this.object.Name}', file offset ${this.object.codeOffset + this.code.Current.Offset} : ${ex.message}\n\n`);
                     if (global.g_cliArgs?.debug) {
@@ -764,7 +1075,7 @@ class PycDecompiler {
             }
         }
     
-        this.cleanBuild = true;
+        this.cleanBuild = this.errors.length === 0;
         let mainNode = new AST.ASTNodeList(this.defBlock.nodes);
         return mainNode;
     }
@@ -1123,10 +1434,19 @@ class PycDecompiler {
                 return true;
             });
             if (aliasName) {
-                const cond = matchType || blk.condition || new AST.ASTName("Exception");
-                blk.condition = new AST.ASTStore(cond, aliasName);
-                if (matchType) {
-                    blk.isExceptStar = true;
+                const existing = blk.condition;
+                if (existing instanceof AST.ASTStore) {
+                    // Condition already encodes `Type as alias` (set by misc_other.js
+                    // POP_TOP→STORE_FAST→POP_TOP path). Don't double-wrap.
+                    if (matchType) {
+                        blk.isExceptStar = true;
+                    }
+                } else {
+                    const cond = matchType || existing || new AST.ASTName("Exception");
+                    blk.condition = new AST.ASTStore(cond, aliasName);
+                    if (matchType) {
+                        blk.isExceptStar = true;
+                    }
                 }
             }
             if (blk.m_nodes.length > 3) {
@@ -1256,14 +1576,15 @@ class PycDecompiler {
                 const alias = node.condition instanceof AST.ASTStore ? node.condition.dest : null;
                 const filtered = (node.nodes || []).filter(n => !isCleanupNode(n, alias));
 
-                // If an except handler has been reduced to empty but still has a condition, keep it with 'pass'
-                // to preserve the handler rather than dropping it entirely.
-                if (node.condition && filtered.length === 0) {
+                // Only synthetic except* handlers without a condition AND no real body
+                // should be dropped; user-written `except:` and `except E:` blocks must
+                // be preserved (with `pass` if the body was nothing but cleanup).
+                if (filtered.length === 0) {
                     node.m_nodes = [new AST.ASTKeyword(AST.ASTKeyword.Word.Pass)];
                 } else if (filtered.length !== (node.nodes || []).length) {
                     node.m_nodes = filtered;
                 }
-                if (Array.isArray(parentArr) && (!node.nodes || node.nodes.length === 0)) {
+                if (Array.isArray(parentArr) && node.isExceptStar && !node.condition && filtered.length === 0) {
                     parentArr.splice(idx, 1);
                     continue;
                 }
@@ -1361,28 +1682,104 @@ class PycDecompiler {
     }
 
     rewriteClassDefinitions(root) {
-        if (!(root instanceof AST.ASTNodeList)) {
-            return;
-        }
+        const hasDataclass = (root instanceof AST.ASTNodeList) && this.astHasDataclassImport(root);
+        this._rewriteClassDefsInNodes(this._collectStatementNodes(root), hasDataclass, new Set());
+    }
 
-        const hasDataclass = this.astHasDataclassImport(root);
+    _collectStatementNodes(container) {
+        if (!container) return [];
+        if (container instanceof AST.ASTNodeList) return container.list;
+        if (container instanceof AST.ASTBlock) return container.nodes;
+        return [];
+    }
 
-        for (const node of root.list) {
-            if (!(node instanceof AST.ASTStore)) {
-                continue;
+    _rewriteClassDefsInNodes(nodes, hasDataclass, visited) {
+        if (!Array.isArray(nodes) || visited.has(nodes)) return;
+        visited.add(nodes);
+
+        for (const node of nodes) {
+            if (node instanceof AST.ASTStore) {
+                this._maybeRewriteClassStore(node, hasDataclass);
+            }
+            for (const child of this._childContainers(node)) {
+                this._rewriteClassDefsInNodes(child, hasDataclass, visited);
             }
+        }
+    }
 
-            if (node.src instanceof AST.ASTCall && node.src.func instanceof AST.ASTClass &&
-                this.isPlainClassCall(node.src)) {
-                node.src = node.src.func;
-                this.cleanupClassBody(node.src);
-                if (hasDataclass) {
-                    node.addDecorator(new AST.ASTName('dataclass'));
-                }
-            } else if (node.src instanceof AST.ASTClass) {
-                this.cleanupClassBody(node.src);
+    _maybeRewriteClassStore(node, hasDataclass) {
+        if (node.src instanceof AST.ASTCall && node.src.func instanceof AST.ASTClass &&
+            this.isPlainClassCall(node.src)) {
+            node.src = node.src.func;
+            this.cleanupClassBody(node.src);
+            if (hasDataclass) {
+                node.addDecorator(new AST.ASTName('dataclass'));
+            }
+        } else if (node.src instanceof AST.ASTCall && node.src.func instanceof AST.ASTClass &&
+                   this.isClassCallWithOnlyKwargs(node.src)) {
+            const callNode = node.src;
+            const classNode = callNode.func;
+            classNode.kwargs = callNode.kwparams || [];
+            node.src = classNode;
+            this.cleanupClassBody(classNode);
+            if (hasDataclass) {
+                node.addDecorator(new AST.ASTName('dataclass'));
+            }
+        } else if (node.src instanceof AST.ASTCall && this.isDecoratedClassCall(node.src)) {
+            // Pattern: `Name = decorator(ClassLiteral[, ...])` produced by Py3.12+
+            // dataclass/decorator-of-class flows. Promote to a real class with
+            // the call-of-decorator attached as an @decorator.
+            const call = node.src;
+            const classNode = call.pparams[0];
+            const decoratorExpr = this._buildDecoratorExpr(call);
+            node.src = classNode;
+            this.cleanupClassBody(classNode);
+            if (decoratorExpr) {
+                node.addDecorator(decoratorExpr);
+            }
+        } else if (node.src instanceof AST.ASTClass) {
+            this.cleanupClassBody(node.src);
+        }
+    }
+
+    isDecoratedClassCall(call) {
+        if (!(call instanceof AST.ASTCall)) return false;
+        if (call.func instanceof AST.ASTClass) return false;
+        if (!call.pparams || call.pparams.length < 1) return false;
+        if (!(call.pparams[0] instanceof AST.ASTClass)) return false;
+        // Any further pparams would become positional args to the decorator,
+        // which cannot be expressed as `@decorator(class)` sugar. Reject.
+        return call.pparams.length === 1;
+    }
+
+    _buildDecoratorExpr(call) {
+        // `decorator(class)` → `@decorator`
+        // `decorator(class, kw=val, ...)` → `@decorator(kw=val, ...)`
+        const kwargs = call.kwparams || [];
+        if (kwargs.length === 0 && !call.hasVar && !call.hasKw) {
+            return call.func;
+        }
+        const wrapper = new AST.ASTCall(call.func, [], kwargs);
+        wrapper.line = call.line;
+        return wrapper;
+    }
+
+    _childContainers(node) {
+        const containers = [];
+        if (node instanceof AST.ASTBlock) {
+            containers.push(node.nodes);
+        }
+        if (node?.body && (node.body instanceof AST.ASTBlock || node.body instanceof AST.ASTNodeList)) {
+            containers.push(this._collectStatementNodes(node.body));
+        }
+        // Generic walk for nested blocks/lists in object properties (e.g. ifBlock.elseBlock).
+        for (const key of ['elseBlock', 'finallyBlock', 'tryBlock', 'thenBlock']) {
+            const val = node?.[key];
+            if (val instanceof AST.ASTBlock || val instanceof AST.ASTNodeList) {
+                containers.push(this._collectStatementNodes(val));
             }
         }
+        return containers;
     }
 
     isPlainClassCall(call) {
@@ -1395,6 +1792,15 @@ class PycDecompiler {
         return !hasParams;
     }
 
+    isClassCallWithOnlyKwargs(call) {
+        if (!(call.func instanceof AST.ASTClass)) {
+            return false;
+        }
+        const hasPparams = call.pparams && call.pparams.length > 0;
+        const hasKwparams = call.kwparams && call.kwparams.length > 0;
+        return !hasPparams && hasKwparams && !call.hasVar && !call.hasKw;
+    }
+
     astHasDataclassImport(root) {
         if (!(root instanceof AST.ASTNodeList)) {
             return false;
@@ -1501,6 +1907,539 @@ class PycDecompiler {
         }
     }
 
+    // Rewrites 3.11+ CHECK_EXC_MATCH artifacts that leaked past block
+    // reconstruction: unwraps `except <exc> EXC_MATCH <type>` conditions
+    // down to `<type>`, rewrites sibling `while __exception__ EXC_MATCH T:`
+    // blocks into `except T:` handlers on the preceding Try, and strips
+    // trailing compiler-generated reraise/cleanup nodes (bare `raise`,
+    // `e = None; del e`, empty `try: pass`). Runs once on the whole tree.
+    cleanupExcMatchArtifacts(root) {
+        // CHECK_EXC_MATCH only exists in Py3.11+; earlier versions never produce
+        // the EXC_MATCH compare op or the __exception__ sentinel, so skip.
+        if (this.object.Reader.versionCompare(3, 11) < 0) return;
+
+        const EXC_MATCH = AST.ASTCompare.CompareOp.Exception;
+
+        const unwrapExcMatch = (cond) => {
+            if (!cond) return cond;
+            // The condition may have been wrapped in ASTStore (alias binding) -
+            // unwrap first, then strip the EXC_MATCH compare.
+            let inner = cond;
+            if (inner instanceof AST.ASTStore && inner.src) {
+                inner = inner.src;
+            }
+            if (inner instanceof AST.ASTCompare && inner.op === EXC_MATCH) {
+                return inner.right;
+            }
+            return cond;
+        };
+
+        const isExcMatchCompare = (node) =>
+            node instanceof AST.ASTCompare && node.op === EXC_MATCH;
+
+        const isExceptionName = (node) =>
+            node instanceof AST.ASTName && node.name === '__exception__';
+
+        const containsExceptionRef = (node, depth = 0) => {
+            if (!node || depth > 4) return false;
+            if (isExceptionName(node)) return true;
+            if (node instanceof AST.ASTCompare || node instanceof AST.ASTBinary) {
+                return containsExceptionRef(node.left, depth + 1) ||
+                       containsExceptionRef(node.right, depth + 1);
+            }
+            if (node instanceof AST.ASTCall) {
+                return containsExceptionRef(node.func, depth + 1) ||
+                       (node.pparams || []).some(p => containsExceptionRef(p, depth + 1));
+            }
+            if (node instanceof AST.ASTStore) {
+                return containsExceptionRef(node.src, depth + 1);
+            }
+            return false;
+        };
+
+        const isEmptyTryBlock = (node) =>
+            node instanceof AST.ASTBlock &&
+            node.blockType === AST.ASTBlock.BlockType.Try &&
+            (node.nodes.length === 0 ||
+             (node.nodes.length === 1 &&
+              node.nodes[0] instanceof AST.ASTKeyword &&
+              node.nodes[0].key === AST.ASTKeyword.Word.Pass));
+
+        const isOrphanExceptionStmt = (node) => {
+            // Bare `raise` with no params → fall-through RERAISE artifact
+            if (node instanceof AST.ASTRaise && (!node.params || node.params.length === 0)) {
+                return true;
+            }
+            // `__exception__(None, None, None)` or `__exception__` alone
+            if (node instanceof AST.ASTCall && isExceptionName(node.func)) {
+                return true;
+            }
+            if (isExceptionName(node)) {
+                return true;
+            }
+            // `x = __exception__` - CPython alias-clear artifact
+            if (node instanceof AST.ASTStore && isExceptionName(node.src)) {
+                return true;
+            }
+            // `return __exception__` - misrendered reraise epilogue
+            if (node instanceof AST.ASTReturn && isExceptionName(node.value)) {
+                return true;
+            }
+            return false;
+        };
+
+        const rewriteContainer = (nodes, parentBlockType) => {
+            if (!Array.isArray(nodes)) return;
+
+            // Pass 1: unwrap EXC_MATCH in Except block conditions.
+            for (const node of nodes) {
+                if (node instanceof AST.ASTCondBlock &&
+                    node.blockType === AST.ASTBlock.BlockType.Except) {
+                    node.condition = unwrapExcMatch(node.condition);
+                }
+            }
+
+            // Pass 2: convert ASTWhile/ASTIf with EXC_MATCH condition to Except
+            // handlers and attach them to the preceding Try block. If no preceding
+            // Try exists (deeply misparsed region), drop them to avoid invalid output.
+            for (let i = nodes.length - 1; i >= 0; i--) {
+                const node = nodes[i];
+                if (!(node instanceof AST.ASTCondBlock) ||
+                    !(node.blockType === AST.ASTBlock.BlockType.While ||
+                      node.blockType === AST.ASTBlock.BlockType.If)) {
+                    continue;
+                }
+                if (!isExcMatchCompare(node.condition) ||
+                    !containsExceptionRef(node.condition.left)) {
+                    continue;
+                }
+                const matchType = node.condition.right;
+                // Find nearest preceding Try block in this container.
+                let tryIdx = -1;
+                for (let j = i - 1; j >= 0; j--) {
+                    const cand = nodes[j];
+                    if (cand instanceof AST.ASTBlock &&
+                        cand.blockType === AST.ASTBlock.BlockType.Try) {
+                        tryIdx = j;
+                        break;
+                    }
+                    // Allow existing Except handlers between; skip past them.
+                    if (cand instanceof AST.ASTCondBlock &&
+                        cand.blockType === AST.ASTBlock.BlockType.Except) {
+                        continue;
+                    }
+                    break;
+                }
+                // Strip any trailing orphan reraise/alias-clear statements from body.
+                const cleanBody = node.nodes.filter(n => !isOrphanExceptionStmt(n));
+                if (cleanBody.length === 0) {
+                    cleanBody.push(new AST.ASTKeyword(AST.ASTKeyword.Word.Pass));
+                }
+
+                if (tryIdx >= 0) {
+                    const exceptBlk = new AST.ASTCondBlock(
+                        AST.ASTBlock.BlockType.Except,
+                        node.start, node.end, matchType, false);
+                    exceptBlk.line = node.line;
+                    exceptBlk.m_nodes = cleanBody;
+                    // Insert right after last existing Except handler for that Try.
+                    let insertAt = tryIdx + 1;
+                    while (insertAt < nodes.length &&
+                           nodes[insertAt] instanceof AST.ASTCondBlock &&
+                           nodes[insertAt].blockType === AST.ASTBlock.BlockType.Except) {
+                        insertAt++;
+                    }
+                    nodes.splice(i, 1);
+                    if (insertAt > i) insertAt--;
+                    nodes.splice(insertAt, 0, exceptBlk);
+                } else {
+                    // No Try to attach to — dropping keeps output parseable.
+                    nodes.splice(i, 1);
+                }
+            }
+
+            // Pass 3: strip orphan exception-related statements at container
+            // level — but NOT inside Except/Finally bodies, where bare `raise`
+            // is a legitimate re-raise statement.
+            const inHandlerBody = parentBlockType === AST.ASTBlock.BlockType.Except ||
+                                  parentBlockType === AST.ASTBlock.BlockType.Finally;
+            if (!inHandlerBody) {
+                for (let i = nodes.length - 1; i >= 0; i--) {
+                    if (isOrphanExceptionStmt(nodes[i])) {
+                        nodes.splice(i, 1);
+                    }
+                }
+            }
+
+            // Pass 3.5: strip `X = None; del X` pairs — CPython 3.11+ emits this
+            // at the tail/fall-through of every `except Foo as X:` body to clear
+            // the binding. The pattern is synthetic and user code effectively
+            // never writes it literally, so removing it is safe and prevents
+            // the artifact from breaking up adjacent except clauses.
+            for (let i = nodes.length - 2; i >= 0; i--) {
+                const a = nodes[i], b = nodes[i + 1];
+                if (a instanceof AST.ASTStore &&
+                    a.src instanceof AST.ASTNone &&
+                    a.dest instanceof AST.ASTName &&
+                    b instanceof AST.ASTDelete &&
+                    b.value instanceof AST.ASTName &&
+                    a.dest.name === b.value.name) {
+                    nodes.splice(i, 2);
+                }
+            }
+
+            // Pass 4: drop empty `try:` blocks. With no following handler the
+            // try is a bare leftover. With a trivial `except: pass` handler the
+            // whole pair is a reconstruction artifact — Python forbids
+            // `try:<empty>`, so either outcome requires the try to go. When the
+            // handler has real body drop only the try and splice a `pass`
+            // placeholder into the handler's matching — but the current
+            // sightings all have pass-only handlers, so mirror that case.
+            const isTrivialHandlerBlock = (n) =>
+                n instanceof AST.ASTCondBlock &&
+                (n.blockType === AST.ASTBlock.BlockType.Except ||
+                 n.blockType === AST.ASTBlock.BlockType.Finally) &&
+                (n.nodes.length === 0 ||
+                 (n.nodes.length === 1 &&
+                  n.nodes[0] instanceof AST.ASTKeyword &&
+                  n.nodes[0].key === AST.ASTKeyword.Word.Pass));
+            for (let i = nodes.length - 1; i >= 0; i--) {
+                if (!isEmptyTryBlock(nodes[i])) continue;
+                const next = nodes[i + 1];
+                const hasHandler = next instanceof AST.ASTCondBlock &&
+                    (next.blockType === AST.ASTBlock.BlockType.Except ||
+                     next.blockType === AST.ASTBlock.BlockType.Finally);
+                if (!hasHandler) {
+                    nodes.splice(i, 1);
+                    continue;
+                }
+                // Walk all trailing handlers; drop the whole cluster iff every
+                // one is a trivial pass-body — keeping any would still leave
+                // the empty try as a syntax error anyway.
+                let tailEnd = i + 1;
+                while (tailEnd < nodes.length && isTrivialHandlerBlock(nodes[tailEnd])) {
+                    tailEnd++;
+                }
+                const allTrivial = tailEnd > i + 1 &&
+                    nodes.slice(i + 1, tailEnd).every(isTrivialHandlerBlock) &&
+                    (tailEnd === nodes.length ||
+                     !(nodes[tailEnd] instanceof AST.ASTCondBlock &&
+                       (nodes[tailEnd].blockType === AST.ASTBlock.BlockType.Except ||
+                        nodes[tailEnd].blockType === AST.ASTBlock.BlockType.Finally)));
+                if (allTrivial) {
+                    nodes.splice(i, tailEnd - i);
+                }
+            }
+
+            // Pass 4.5: move a sibling Except/Finally that immediately follows
+            // a Try into the Try's body. When CFG reconstruction hoists the
+            // handler one level up (e.g. into the parent Else), the block
+            // renderer dedents `except:` to the parent's indent — producing
+            // `else: / try: / except:` where `except:` lands at the `else:`
+            // column instead of the `try:` column, which is a SyntaxError.
+            // Absorbing the handler into the Try body lets the renderer's
+            // single-step dedent land it at the correct `try:` column.
+            for (let i = 0; i < nodes.length - 1; i++) {
+                const cur = nodes[i];
+                if (!(cur instanceof AST.ASTBlock) ||
+                    cur.blockType !== AST.ASTBlock.BlockType.Try) continue;
+                const next = nodes[i + 1];
+                if (!(next instanceof AST.ASTCondBlock)) continue;
+                if (next.blockType !== AST.ASTBlock.BlockType.Except &&
+                    next.blockType !== AST.ASTBlock.BlockType.Finally) continue;
+                // Skip if the Try already carries its own trailing handler —
+                // moving another one in would stack two handlers, which is
+                // only valid for multi-except chains (same Try). Those cases
+                // already render fine.
+                const last = cur.nodes[cur.nodes.length - 1];
+                const hasOwnHandler = last instanceof AST.ASTCondBlock &&
+                    (last.blockType === AST.ASTBlock.BlockType.Except ||
+                     last.blockType === AST.ASTBlock.BlockType.Finally);
+                if (hasOwnHandler) continue;
+                // Empty Try bodies + non-trivial handler would collapse to an
+                // invalid `try: / except:` with nothing between. Inject a
+                // `pass` so the rendered block is syntactically valid.
+                if (cur.nodes.length === 0) {
+                    cur.nodes.push(new AST.ASTKeyword(AST.ASTKeyword.Word.Pass));
+                }
+                cur.nodes.push(next);
+                nodes.splice(i + 1, 1);
+            }
+
+            // Pass 5: a Try block with a non-empty body but no following
+            // Except/Finally handler is a SyntaxError. Append a synthetic
+            // `except: pass` so the output parses — real structural recovery
+            // needs dedicated work, but the fallback keeps the file usable.
+            // Skip when the Try already has an Except/Finally nested in its
+            // body (except* groups build nested handler structures).
+            for (let i = 0; i < nodes.length; i++) {
+                const cur = nodes[i];
+                if (!(cur instanceof AST.ASTBlock) ||
+                    cur.blockType !== AST.ASTBlock.BlockType.Try) {
+                    continue;
+                }
+                if (cur.nodes.length === 0) continue;
+                const next = nodes[i + 1];
+                const hasHandler = next instanceof AST.ASTCondBlock &&
+                    (next.blockType === AST.ASTBlock.BlockType.Except ||
+                     next.blockType === AST.ASTBlock.BlockType.Finally);
+                if (hasHandler) continue;
+                const hasNestedExcept = cur.nodes.some(n =>
+                    n instanceof AST.ASTCondBlock &&
+                    (n.blockType === AST.ASTBlock.BlockType.Except ||
+                     n.blockType === AST.ASTBlock.BlockType.Finally));
+                if (hasNestedExcept) continue;
+                const synthetic = new AST.ASTCondBlock(
+                    AST.ASTBlock.BlockType.Except,
+                    cur.end, cur.end, null, false);
+                synthetic.line = cur.line;
+                synthetic.m_nodes.push(new AST.ASTKeyword(AST.ASTKeyword.Word.Pass));
+                nodes.splice(i + 1, 0, synthetic);
+                i++;
+            }
+
+            // Pass 5.5: adopt orphan Except into a preceding branch whose
+            // body ends with an un-paired Try. CPython can emit a try/except
+            // inside the tail of an if/else branch so that, after CFG
+            // reconstruction, the Try ends up as the last child of the branch
+            // while its handler gets hoisted one level up as a stray sibling.
+            // Moving the handler back in keeps the pair valid. Absorbed
+            // trailing statements stay in the handler body — not semantically
+            // correct, but renders to parseable Python instead of a stray
+            // `except:` at the outer indent.
+            const branchTypes = [
+                AST.ASTBlock.BlockType.If,
+                AST.ASTBlock.BlockType.Elif,
+                AST.ASTBlock.BlockType.Else,
+            ];
+            const endsWithOrphanTry = (block) => {
+                if (!(block instanceof AST.ASTBlock)) return false;
+                if (!branchTypes.includes(block.blockType)) return false;
+                const body = block.nodes;
+                if (!body || body.length === 0) return false;
+                const last = body[body.length - 1];
+                if (!(last instanceof AST.ASTBlock) ||
+                    last.blockType !== AST.ASTBlock.BlockType.Try) {
+                    return false;
+                }
+                const hasHandlerInside = last.nodes.some(n =>
+                    n instanceof AST.ASTCondBlock &&
+                    (n.blockType === AST.ASTBlock.BlockType.Except ||
+                     n.blockType === AST.ASTBlock.BlockType.Finally));
+                return !hasHandlerInside;
+            };
+            for (let i = nodes.length - 1; i > 0; i--) {
+                const cur = nodes[i];
+                if (!(cur instanceof AST.ASTCondBlock)) continue;
+                if (cur.blockType !== AST.ASTBlock.BlockType.Except &&
+                    cur.blockType !== AST.ASTBlock.BlockType.Finally) continue;
+                const prev = nodes[i - 1];
+                if (!endsWithOrphanTry(prev)) continue;
+                // Confirm there's no matching Try at this container level,
+                // otherwise leave the pair alone.
+                let hasLocalTry = false;
+                for (let j = i - 1; j >= 0; j--) {
+                    const p = nodes[j];
+                    if (p instanceof AST.ASTBlock &&
+                        p.blockType === AST.ASTBlock.BlockType.Try) {
+                        hasLocalTry = true;
+                        break;
+                    }
+                    if (p instanceof AST.ASTCondBlock &&
+                        (p.blockType === AST.ASTBlock.BlockType.Except ||
+                         p.blockType === AST.ASTBlock.BlockType.Finally)) {
+                        continue;
+                    }
+                    break;
+                }
+                if (hasLocalTry) continue;
+                prev.nodes.push(cur);
+                nodes.splice(i, 1);
+            }
+
+            // Pass 6: drop orphan Except/Finally blocks that have no matching
+            // Try (or preceding Except) anywhere earlier in this container.
+            // These are leftovers from misreconstructed CFGs — keeping them
+            // produces SyntaxError at parse time. Inside a Try body Except
+            // can legitimately nest (Py3.11+ handler layout, except* groups),
+            // but only at the tail. A mid-body Except with non-handler
+            // statements after it is a stray handler — drop it.
+            const inTryBody = parentBlockType === AST.ASTBlock.BlockType.Try;
+            const isHandlerBlock = (x) =>
+                x instanceof AST.ASTCondBlock &&
+                (x.blockType === AST.ASTBlock.BlockType.Except ||
+                 x.blockType === AST.ASTBlock.BlockType.Finally);
+            for (let i = nodes.length - 1; i >= 0; i--) {
+                const cur = nodes[i];
+                if (!(cur instanceof AST.ASTCondBlock)) continue;
+                if (cur.blockType !== AST.ASTBlock.BlockType.Except &&
+                    cur.blockType !== AST.ASTBlock.BlockType.Finally) continue;
+                if (inTryBody) {
+                    // except* groups have complex internal structure — never
+                    // touch them.
+                    if (cur.isExceptStar) continue;
+                    // For regular Except nested inside Try body (Py3.11+
+                    // handler layout): legitimate only when at the tail.
+                    let allTrailingHandlers = true;
+                    for (let k = i + 1; k < nodes.length; k++) {
+                        if (!isHandlerBlock(nodes[k])) {
+                            allTrailingHandlers = false;
+                            break;
+                        }
+                    }
+                    if (allTrailingHandlers) continue;
+                }
+                let anchorFound = false;
+                for (let j = i - 1; j >= 0; j--) {
+                    const prev = nodes[j];
+                    if (prev instanceof AST.ASTBlock &&
+                        prev.blockType === AST.ASTBlock.BlockType.Try) {
+                        anchorFound = true;
+                        break;
+                    }
+                    if (prev instanceof AST.ASTCondBlock &&
+                        (prev.blockType === AST.ASTBlock.BlockType.Except ||
+                         prev.blockType === AST.ASTBlock.BlockType.Finally)) {
+                        continue;
+                    }
+                    break;
+                }
+                if (!anchorFound) nodes.splice(i, 1);
+            }
+
+            // Pass 7: after earlier passes may have emptied a Try body, drop
+            // Try+trivial-Except pairs where the body is now empty. Python
+            // forbids `try:` with no body; a pass-only handler carries no
+            // recoverable intent, so splice the cluster out entirely.
+            for (let i = nodes.length - 1; i >= 0; i--) {
+                if (!isEmptyTryBlock(nodes[i])) continue;
+                let tailEnd = i + 1;
+                while (tailEnd < nodes.length && isTrivialHandlerBlock(nodes[tailEnd])) {
+                    tailEnd++;
+                }
+                if (tailEnd === i + 1) continue;
+                const trailingHandler = nodes[tailEnd] instanceof AST.ASTCondBlock &&
+                    (nodes[tailEnd].blockType === AST.ASTBlock.BlockType.Except ||
+                     nodes[tailEnd].blockType === AST.ASTBlock.BlockType.Finally);
+                if (trailingHandler) continue;
+                nodes.splice(i, tailEnd - i);
+            }
+        };
+
+        // Post-order traversal: process children before parent so nested
+        // emptyings bubble up — an outer Try can only be recognised as empty
+        // after the inner Try/Except artifacts inside its body were dropped.
+        const visited = new WeakSet();
+        const visit = (n) => {
+            if (!n || visited.has(n)) return;
+            visited.add(n);
+            let nodes = null;
+            let parentType = null;
+            if (n instanceof AST.ASTNodeList) {
+                nodes = n.list;
+                parentType = null;
+            } else if (n instanceof AST.ASTBlock) {
+                nodes = n.nodes;
+                parentType = n.blockType;
+            } else if (n instanceof AST.ASTStore && n.src instanceof AST.ASTFunction) {
+                const body = n.src.code?.object?.SourceCode;
+                if (body) visit(body);
+                return;
+            }
+            if (nodes) {
+                for (const c of nodes) visit(c);
+                rewriteContainer(nodes, parentType);
+            }
+        };
+        visit(root);
+    }
+
+    // An Except block can get reconstructed inside a non-Try block's body
+    // (most often a For/While/If inside the protected try-body) when the
+    // handler's offset range overlaps a nested loop. Python requires the
+    // except clause to sit next to its `try:`, so walk the tree and pull
+    // such Except blocks out of any non-Try ancestor until they become a
+    // sibling of their enclosing Try.
+    hoistNestedExceptBlocks(root) {
+        const isHoistableBlock = (node) =>
+            node instanceof AST.ASTBlock &&
+            node.blockType !== AST.ASTBlock.BlockType.Try;
+
+        const isExcept = (node) =>
+            node instanceof AST.ASTCondBlock &&
+            node.blockType === AST.ASTBlock.BlockType.Except;
+
+        // Fixed-point loop: one pass hoists Except up one level. Bounded by
+        // tree depth; excessive iterations just exit.
+        for (let iter = 0; iter < 64; iter++) {
+            let moved = false;
+            const stack = [{container: null, nodes: null, parent: null}];
+            const parentMap = new WeakMap(); // child container → {arr, index, parent}
+
+            const visit = (arr, parentInfo) => {
+                for (let i = 0; i < arr.length; i++) {
+                    const n = arr[i];
+                    if (!n) continue;
+                    let children = null;
+                    if (n instanceof AST.ASTBlock || n instanceof AST.ASTCondBlock) {
+                        children = n.nodes;
+                    } else if (n instanceof AST.ASTNodeList) {
+                        children = n.list;
+                    } else if (n instanceof AST.ASTStore && n.src instanceof AST.ASTFunction) {
+                        const src = n.src.code?.object?.SourceCode;
+                        if (src instanceof AST.ASTNodeList) {
+                            visit(src.list, null);
+                        }
+                        continue;
+                    }
+                    if (Array.isArray(children) && children.length > 0) {
+                        // If this block is non-Try and its first child is an
+                        // Except, pull that Except out into the parent arr
+                        // right after `n`.
+                        if (isHoistableBlock(n)) {
+                            // Scan forward for leading Except children only;
+                            // an Except appearing later in the body is usually
+                            // a real construct we should leave alone.
+                            while (children.length > 0 && isExcept(children[0])) {
+                                const ex = children.shift();
+                                arr.splice(i + 1, 0, ex);
+                                moved = true;
+                            }
+                        }
+                        visit(children, {arr, index: i});
+                    }
+                }
+            };
+
+            const roots = [];
+            if (root instanceof AST.ASTNodeList) roots.push(root.list);
+            else if (root instanceof AST.ASTBlock) roots.push(root.nodes);
+
+            for (const r of roots) visit(r, null);
+
+            // Also dive into nested function bodies.
+            const walk = (n, seen) => {
+                if (!n || seen.has(n)) return;
+                seen.add(n);
+                if (n instanceof AST.ASTStore && n.src instanceof AST.ASTFunction) {
+                    const src = n.src.code?.object?.SourceCode;
+                    if (src instanceof AST.ASTNodeList) {
+                        visit(src.list, null);
+                    }
+                }
+                let children = null;
+                if (n instanceof AST.ASTNodeList) children = n.list;
+                else if (n instanceof AST.ASTBlock || n instanceof AST.ASTCondBlock) children = n.nodes;
+                if (Array.isArray(children)) {
+                    for (const c of children) walk(c, seen);
+                }
+            };
+            walk(root, new WeakSet());
+
+            if (!moved) break;
+        }
+    }
+
     dedupeExceptHandlers(root) {
         const queue = [root];
         const visited = new WeakSet();
@@ -1520,12 +2459,23 @@ class PycDecompiler {
                     }
                 }
 
-                // Drop trivial generic except handlers that only contain pass/cleanup.
+                // Drop trivial generic except* handlers (exception-group artifacts) that only contain pass/cleanup.
+                // User-written `except:` and `except Exception:` must be preserved.
+                // Python forbids mixing `except` and `except*` inside the same try, so a
+                // non-star trivial `except Exception [as X]: pass` in a try that has any
+                // `except*` sibling is always a decompiler artifact.
+                const hasExceptStarSibling = nodes.some(n =>
+                    n instanceof AST.ASTCondBlock &&
+                    n.blockType === AST.ASTBlock.BlockType.Except &&
+                    n.isExceptStar);
                 for (let i = nodes.length - 1; i >= 0; i--) {
                     const blk = nodes[i];
                     if (!(blk instanceof AST.ASTCondBlock) || blk.blockType !== AST.ASTBlock.BlockType.Except) {
                         continue;
                     }
+                    if (!blk.isExceptStar && !hasExceptStarSibling) {
+                        continue;
+                    }
                     const condNode = blk.condition instanceof AST.ASTStore ? blk.condition.src : blk.condition;
                     const condText = (typeof condNode?.codeFragment === 'function' ? condNode.codeFragment()?.toString?.() : null) || condNode?.name;
                     const body = blk.nodes || [];
@@ -1603,6 +2553,11 @@ class PycDecompiler {
         if (!(node instanceof AST.ASTCondBlock)) {
             return false;
         }
+        // `while True: pass` / `while 1:` has no explicit condition but is a legitimate
+        // user construct; only If blocks are null-sentinel artifacts from with-cleanup.
+        if (node.blockType !== AST.ASTBlock.BlockType.If) {
+            return false;
+        }
         const condition = node.condition;
 
         // Drop degenerate IF blocks with no condition and empty body (often leftover from with cleanup tests)
@@ -1769,6 +2724,14 @@ class PycDecompiler {
                     const frag = ch?.codeFragment?.()?.toString?.() || "";
                     return frag === "pass" || frag.includes("__exception__") || frag.includes("##ERROR##");
                 }))) {
+                // Drop only synthetic except* handlers without a user condition.
+                // User-written `except:` / `except E:` must be preserved; replace
+                // cleanup-only body with `pass` so the try statement stays valid.
+                if (node.isExceptStar && !node.condition) {
+                    continue;
+                }
+                node.m_nodes = [new AST.ASTKeyword(AST.ASTKeyword.Word.Pass)];
+                rewritten.push(node);
                 continue;
             }
             if (typeof node?.codeFragment === 'function') {
@@ -1843,25 +2806,72 @@ class PycDecompiler {
             }
 
             const targetName = node.dest?.name || node.dest?.codeFragment?.();
+            const isClassLike = targetName && targetName[0] === targetName[0]?.toUpperCase?.();
+
+            // Preferred path (3.13+): the wrapper's own SourceCode ends with
+            // `return <ASTFunction>` where the function already has correct
+            // annotations (via SET_FUNCTION_ATTRIBUTE) and typeParams with
+            // PEP 696 defaults (via CALL_INTRINSIC_2 intrinsics 5 + 4).
+            const wrapperBody = func.code?.object?.SourceCode?.list || [];
+            let returnedNode = null;
+            for (let j = wrapperBody.length - 1; j >= 0; j--) {
+                const stmt = wrapperBody[j];
+                if (stmt instanceof AST.ASTReturn && stmt.value) {
+                    returnedNode = stmt.value;
+                    break;
+                }
+            }
+            if (!isClassLike && returnedNode instanceof AST.ASTFunction) {
+                node.m_src = returnedNode;
+                continue;
+            }
+            // Classes: the wrapper's direct return is an ASTClass whose base is
+            // an internal CPython temp (".generic_base" for SUBSCRIPT_GENERIC).
+            // Fall through to the Consts-based rebuild which infers clean
+            // typeParams from string names instead.
+
+            // Fallback (pre-3.13 or irregular wrappers): rebuild from Consts.
             const codeConsts = func.code?.object?.Consts?.Value || [];
-            const innerCodeObj = codeConsts.find(c => c?.ClassName === 'Py_CodeObject');
+            const allCodeObjects = codeConsts.filter(c => c?.ClassName === 'Py_CodeObject');
+            let innerCodeObj = allCodeObjects.find(c => c.Name?.toString?.() === targetName);
+            if (!innerCodeObj) {
+                innerCodeObj = allCodeObjects[0];
+            }
             if (!innerCodeObj) {
                 continue;
             }
-            // Extract type parameters: pick uppercase-like strings excluding target name
-            const typeParams = codeConsts
+            const typeParamNames = codeConsts
                 .filter(c => c?.ClassName === 'Py_String')
                 .map(c => c.Value)
                 .filter(v => /^[A-Z][A-Za-z0-9_]*$/.test(v || '') && v !== targetName);
 
-            // Decompile inner code object to get body
+            const typeParams = typeParamNames.map(name => {
+                const defaultCode = allCodeObjects.find(c =>
+                    c !== innerCodeObj &&
+                    (c.ArgCount || 0) === 0 &&
+                    c.Name?.toString?.() === name
+                );
+                if (!defaultCode) return name;
+                try {
+                    const dd = new PycDecompiler(defaultCode);
+                    const body = dd.decompile();
+                    defaultCode.SourceCode = body;
+                    if (dd.errors.length) this.errors.push(...dd.errors);
+                    const list = body?.list || [];
+                    const top = list.top?.() || list[list.length - 1] || list[0];
+                    if (top instanceof AST.ASTReturn && top.value) {
+                        return { name, default: top.value };
+                    }
+                } catch (_) { /* fall through */ }
+                return name;
+            });
+
             const innerDecompiler = new PycDecompiler(innerCodeObj);
             const innerBody = innerDecompiler.decompile();
             innerCodeObj.SourceCode = innerBody;
+            if (innerDecompiler.errors.length) this.errors.push(...innerDecompiler.errors);
             const astObj = new AST.ASTObject(innerCodeObj);
 
-            const isClassLike = targetName && targetName[0] === targetName[0]?.toUpperCase?.();
-
             if (!isClassLike) {
                 const fn = new AST.ASTFunction(astObj);
                 fn.annotations = innerDecompiler.funcAnnotations || fn.annotations;