fix: allow dragged C blocks to wrap partial stacks

Resolves #3494

Author: cwillisf

src/index.ts

@@ -47,6 +47,7 @@ import './renderer/cat/renderer'
 import './renderer/renderer'
 import { registerScratchBlockPaster } from './scratch_block_paster'
 import * as scratchBlocksUtils from './scratch_blocks_utils'
+import './scratch_c_block_wrap'
 import './scratch_comment_icon'
 import './scratch_connection_checker'
 import { registerScratchContinuousCategory } from './scratch_continuous_category'

src/scratch_c_block_wrap.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright 2026 Scratch Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as Blockly from 'blockly/core'
+
+/**
+ * When a C-block (a block with a statement input) is dropped onto a block that
+ * is already in the middle of a stack, Blockly's default behaviour reconnects
+ * the displaced block to the C-block's *next* connection (i.e. after the
+ * C-block), leaving the C-block's "mouth" empty.  Scratch expects the
+ * displaced block to be placed *inside* the C-block (wrap behaviour).
+ *
+ * We fix this by patching `Connection.getConnectionForOrphanedConnection` so
+ * that it prefers an available statement-input connection on the dragging block
+ * over the last-next-in-stack connection when the orphan is a statement block.
+ * This applies to both real blocks and insertion markers (drag previews) so
+ * that the preview matches the actual drop result.
+ */
+const originalGetConnectionForOrphanedConnection = Blockly.Connection.getConnectionForOrphanedConnection.bind(
+  Blockly.Connection,
+)
+
+Blockly.Connection.getConnectionForOrphanedConnection = function (
+  startBlock: Blockly.Block,
+  orphanConnection: Blockly.Connection,
+): Blockly.Connection | null {
+  // Apply the wrapping logic when the orphaned connection is a statement
+  // connection (PREVIOUS_STATEMENT).  Value connections (OUTPUT_VALUE) are
+  // already handled by the original implementation.
+  if (orphanConnection.type === Blockly.ConnectionType.PREVIOUS_STATEMENT) {
+    const checker = orphanConnection.getConnectionChecker()
+    for (const input of startBlock.inputList) {
+      const conn = input.connection
+      // Look for an unoccupied statement input (NEXT_STATEMENT) on the
+      // dragging block.  Statement inputs are connections owned by an input
+      // (getParentInput() !== null) rather than the block's own nextConnection.
+      if (
+        conn?.type === Blockly.ConnectionType.NEXT_STATEMENT &&
+        !conn.isConnected() &&
+        checker.canConnect(orphanConnection, conn, false)
+      ) {
+        return conn
+      }
+    }
+  }
+  return originalGetConnectionForOrphanedConnection(startBlock, orphanConnection)
+}
+
+/**
+ * When a drag preview (insertion marker) is cleaned up, Blockly calls
+ * `marker.unplug(true)` which heals the stack by reconnecting the block before
+ * the marker to whatever block was after it (via `marker.nextConnection`).
+ *
+ * Because we now send the displaced block (B2) into the insertion marker's
+ * statement input for a correct visual preview, B2 is no longer at
+ * `marker.nextConnection` when cleanup runs.  The heal step therefore skips B2
+ * and it gets lost when the marker is disposed.
+ *
+ * We fix this by patching `hideInsertionMarker` to restore B2 from the
+ * marker's statement input back to `marker.nextConnection` before the original
+ * cleanup runs, so the standard healing logic reconnects B1.next → B2.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- InsertionMarkerPreviewer does not publicly expose hideInsertionMarker
+const proto = Blockly.InsertionMarkerPreviewer.prototype as any
+const originalHideInsertionMarker = proto.hideInsertionMarker as (markerConn: Blockly.Connection) => void
+proto.hideInsertionMarker = function (this: Blockly.InsertionMarkerPreviewer, markerConn: Blockly.Connection) {
+  const marker = markerConn.getSourceBlock() as Blockly.BlockSvg
+
+  // Restore a real block from a statement input to nextConnection so that
+  // unplug(true) can heal the stack correctly.  Conditions:
+  //   - marker is mid-stack (has a predecessor)
+  //   - marker.nextConnection is empty (displaced block is NOT already there)
+  //   - a non-marker block is sitting in a statement input
+  if (marker.previousConnection?.isConnected() && marker.nextConnection && !marker.nextConnection.isConnected()) {
+    for (const input of marker.inputList) {
+      const conn = input.connection
+      if (conn?.type === Blockly.ConnectionType.NEXT_STATEMENT && conn.isConnected()) {
+        const blockInInput = conn.targetBlock() as Blockly.BlockSvg | null
+        if (blockInInput && !blockInInput.isInsertionMarker()) {
+          const prev = blockInInput.previousConnection
+          if (!prev) continue
+          prev.disconnect()
+          marker.nextConnection.connect(prev)
+          break
+        }
+      }
+    }
+  }
+
+  originalHideInsertionMarker.call(this, markerConn)
+}

tests/unit/c_block_wrap.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Copyright 2026 Scratch Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as Blockly from 'blockly/core'
+import { afterEach, assert, beforeEach, describe, expect, it } from 'vitest'
+// Registers the C-block wrapping fix.
+import '../../src/scratch_c_block_wrap'
+
+let workspace: Blockly.Workspace
+
+beforeEach(() => {
+  workspace = new Blockly.Workspace()
+})
+
+afterEach(() => {
+  workspace.dispose()
+})
+
+describe('C-block wrapping', () => {
+  const BLOCK_TYPES = ['test_c_block_wrap', 'test_stmt_wrap_inner', 'test_stmt_wrap_outer']
+
+  beforeEach(() => {
+    Blockly.defineBlocksWithJsonArray([
+      {
+        type: 'test_c_block_wrap',
+        message0: 'repeat %1',
+        args0: [{ type: 'input_statement', name: 'SUBSTACK' }],
+        previousStatement: null,
+        nextStatement: null,
+      },
+      {
+        type: 'test_stmt_wrap_inner',
+        message0: 'inner block',
+        previousStatement: null,
+        nextStatement: null,
+      },
+      {
+        type: 'test_stmt_wrap_outer',
+        message0: 'outer block',
+        previousStatement: null,
+        nextStatement: null,
+      },
+    ])
+  })
+
+  afterEach(() => {
+    for (const type of BLOCK_TYPES) {
+      delete Blockly.Blocks[type]
+    }
+  })
+
+  it('displaced block goes into statement input when C-block is dropped onto a middle-of-stack block (actual drop)', () => {
+    // Stack: outerBlock → innerBlock
+    const cBlock = workspace.newBlock('test_c_block_wrap')
+    const outerBlock = workspace.newBlock('test_stmt_wrap_outer')
+    const innerBlock = workspace.newBlock('test_stmt_wrap_inner')
+
+    // Connect outerBlock → innerBlock (innerBlock is connected inside an existing stack)
+    assert(outerBlock.nextConnection, 'outerBlock should have nextConnection')
+    assert(innerBlock.previousConnection, 'innerBlock should have previousConnection')
+    outerBlock.nextConnection.connect(innerBlock.previousConnection)
+
+    // Simulate the scenario: the C-block's previous connects to outerBlock's next,
+    // displacing innerBlock. Where should innerBlock (the orphan) go?
+    //
+    // Expected (wrap behavior): into cBlock's statement input (SUBSTACK)
+    // Actual before fix (bug):   after cBlock's next connection
+    const result = Blockly.Connection.getConnectionForOrphanedConnection(cBlock, innerBlock.previousConnection)
+
+    const statementInputConn = cBlock.getInput('SUBSTACK')?.connection
+    assert(statementInputConn, 'cBlock should have a SUBSTACK statement input with a connection')
+
+    expect(result).toBe(statementInputConn)
+  })
+
+  it('hideInsertionMarker restores displaced block from statement input so stack heals correctly', () => {
+    // When a C-block insertion marker is mid-stack with the displaced block (B2)
+    // sitting in its statement input (as placed by our getConnectionForOrphanedConnection
+    // patch), hideInsertionMarker must move B2 back to marker.nextConnection so that
+    // marker.unplug(true) can reconnect B1 → B2 when the preview is dismissed.
+    const b1 = workspace.newBlock('test_stmt_wrap_outer')
+    const marker = workspace.newBlock('test_c_block_wrap')
+    const b2 = workspace.newBlock('test_stmt_wrap_inner')
+
+    marker.setInsertionMarker(true)
+
+    // B1 → marker (marker is mid-stack)
+    assert(b1.nextConnection, 'b1 should have nextConnection')
+    assert(marker.previousConnection, 'marker should have previousConnection')
+    b1.nextConnection.connect(marker.previousConnection)
+
+    // B2 is in the marker's statement input (placed there by our orphan-connection patch)
+    const markerStatementConn = marker.getInput('SUBSTACK')?.connection
+    assert(markerStatementConn, 'marker should have a SUBSTACK statement input')
+    assert(b2.previousConnection, 'b2 should have previousConnection')
+    markerStatementConn.connect(b2.previousConnection)
+
+    // The original hideInsertionMarker does not use `this`, so any object works as context.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call -- tested function does not use `this`
+    ;(Blockly.InsertionMarkerPreviewer.prototype as any).hideInsertionMarker.call({}, marker.previousConnection)
+
+    // After cleanup, the stack should be healed: B1 → B2 (marker was disposed)
+    expect(b1.nextConnection.targetBlock()).toBe(b2)
+  })
+
+  it('displaced block goes into statement input even when C-block is an insertion marker (preview matches drop)', () => {
+    // During drag preview, Blockly creates an insertion marker to visualise
+    // where the dragged block will land.  getConnectionForOrphanedConnection
+    // is called with the MARKER as startBlock.  We want the displaced block to
+    // go into the marker's statement input so the preview matches the actual
+    // drop result (B2 inside C, not after C).  A separate patch in
+    // hideInsertionMarker restores B2 to nextConnection before cleanup so that
+    // unplug(true) can heal the stack correctly when the preview is dismissed.
+    const markerBlock = workspace.newBlock('test_c_block_wrap')
+    markerBlock.setInsertionMarker(true)
+
+    const outerBlock = workspace.newBlock('test_stmt_wrap_outer')
+    const innerBlock = workspace.newBlock('test_stmt_wrap_inner')
+    assert(outerBlock.nextConnection, 'outerBlock should have nextConnection')
+    assert(innerBlock.previousConnection, 'innerBlock should have previousConnection')
+    outerBlock.nextConnection.connect(innerBlock.previousConnection)
+
+    const result = Blockly.Connection.getConnectionForOrphanedConnection(markerBlock, innerBlock.previousConnection)
+
+    const statementInputConn = markerBlock.getInput('SUBSTACK')?.connection
+    assert(statementInputConn, 'markerBlock should have a SUBSTACK statement input with a connection')
+
+    // Should redirect the orphan into the statement input (same as a real block).
+    expect(result).toBe(statementInputConn)
+  })
+})