[green] preserve tablet editing controls around native keyboards

CHANGELOG.md

@@ -10,20 +10,27 @@ or firmware release. Firmware v0.6.1 is published on the owner's confirmation;
 incomplete automated evidence remains pending. The qualified v0.6.0 release
 remains a separate historical baseline built from its annotated tag.
 
-The current compatible app feature set now targets `0.2.0`; build `5` was
-handed off through Transporter for TestFlight. This candidate identity improves
-test and evidence traceability but does not designate a qualified store release
-or claim App Store Connect processing, beta-review approval, or availability.
-The next prepared Android open-testing candidate is `0.2.0 (8)`; its bundle
-and submission packet do not claim Play submission, approval, or rollout.
+The merged app source now targets `0.3.0+9`. Its local Android and iPad Preview
+installations support scoped engineering acceptance for bounded recovery and
+the declared app-only matrix. Device closeout is complete. [PR #41](https://github.com/PyBLE-dev/PyBLE/pull/41) tracks final
+integration; required CI and merge precede publishing. Actual channel delivery
+remains pending. The recorded existing-channel baseline is Android
+Play `0.2.0 (8)` and iPad TestFlight `0.2.0 (6)`; the earlier build-5 Transporter
+and build-8 submission handoffs remain historical artifact records.
 
 ### App source
 
-- Prepared app source candidate `0.3.0+9` with bounded on-device current-text
+- Merged app source candidate `0.3.0+9` with bounded on-device current-text
   recovery using Drift. Exact text and metadata commit atomically; startup
   offers offline preview, Restore and confirmed Discard, with separate local
   checkpoint status and an explicit Save recovery copy action. Storage errors
   preserve the previous copy and live text, with explicit volatile continuation.
+- Fixed landscape editing with the software keyboard open: the console output
+  strip temporarily collapses to its status/actions bar, and navigation
+  destinations remain reachable by scrolling. Expanding requests keyboard
+  dismissal from the current platform window, including native Blocks fields.
+  iPad layout also accounts for keyboards reopened through the keyboard palette
+  without applying the same overlap twice; document/console state is retained.
 - Added document-epoch and connection-session guards for Editor Save/Run,
   Files Open/Upload and Blocks-to-Editor replacement. Restored drafts require
   current-destination confirmation before board writes; a board swap after text

README.md

@@ -75,7 +75,7 @@ fetches and validates the complete batch, shows the exact destination paths,
 and asks separately before overwriting existing files. Import never creates a
 remote folder hierarchy, opens an editor document, or runs downloaded code.
 
-The next App source candidate is `0.3.0+9`; App and firmware versions are
+The merged App source candidate is `0.3.0+9`; App and firmware versions are
 independent. The published Android version is `0.2.0`, available through
 [Google Play open testing](https://play.google.com/store/apps/details?id=dev.pyble.pyble).
 iPad testing continues through TestFlight. The
@@ -93,7 +93,7 @@ same Flutter source and app test gates. The iOS/iPadOS project minimum is 15.
 
 ### Next app candidate: local draft recovery
 
-The `0.3.0+9` source candidate adds one on-device current-text recovery copy.
+The merged `0.3.0+9` candidate adds one on-device current-text recovery copy.
 After restart, preview and explicitly Restore or Discard the last committed
 copy before connecting. “Saved locally” means the matching transaction finished;
 pending edits may not survive immediate termination. The separate **Save
@@ -104,8 +104,12 @@ This bounded feature covers text up to 1 MiB, including Python explicitly copied
 from Blocks. Blocks workspace graphs, projects/history and exported backups
 remain outside this increment. Uninstalling or clearing app data removes local
 copies. See the [candidate execution record](docs/developments/2026-q4-reliable-workflow/c1-s2/00_Execution_Record.md)
-for automated and device evidence; source implementation does not establish
-store availability or release qualification.
+for accepted automated and candidate-specific device evidence, including the
+declared five-profile × two-platform app matrix and test conditions. Local
+Android and iPad Preview installations remain separate from store delivery.
+The [release readiness record](docs/developments/2026-q4-reliable-workflow/c1-s2/06_Release_Readiness.md)
+tracks the engineering-qualified artifacts, completed device closeout and channel handoff;
+`0.3.0 (9)` is not yet established as a store-delivered update.
 
 ### Firmware
 

app/android/app/src/main/kotlin/dev/pyble/pyble/MainActivity.kt

@@ -1,5 +1,28 @@
+// SPDX-License-Identifier: MIT
+// Part of PyBLE (https://pyble.dev) — see /LICENSE.
+
 package dev.pyble.pyble
 
+import android.view.inputmethod.InputMethodManager
 import io.flutter.embedding.android.FlutterActivity
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.plugin.common.MethodChannel
 
-class MainActivity : FlutterActivity()
+class MainActivity : FlutterActivity() {
+    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+        super.configureFlutterEngine(flutterEngine)
+        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "dev.pyble/keyboard")
+            .setMethodCallHandler { call, result ->
+                if (call.method == "dismissKeyboard") {
+                    val manager = getSystemService(InputMethodManager::class.java)
+                    window.decorView.windowToken?.let { token ->
+                        manager?.hideSoftInputFromWindow(token, 0)
+                    }
+                    // Acknowledge the request; Flutter observes actual view insets.
+                    result.success(null)
+                } else {
+                    result.notImplemented()
+                }
+            }
+    }
+}

app/ios/Runner/AppDelegate.swift

@@ -1,8 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Part of PyBLE (https://pyble.dev) — see /LICENSE.
+
 import Flutter
 import UIKit
 
 @main
 @objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
+  private var keyboardInsets: PybleKeyboardInsets?
+
   override func application(
     _ application: UIApplication,
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
@@ -12,5 +17,125 @@ import UIKit
 
   func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
     GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
+    guard let registrar = engineBridge.pluginRegistry.registrar(forPlugin: "PybleKeyboardDismissal")
+    else { return }
+    keyboardInsets = PybleKeyboardInsets(registrar: registrar)
+    let keyboard = FlutterMethodChannel(
+      name: "dev.pyble/keyboard", binaryMessenger: registrar.messenger())
+    keyboard.setMethodCallHandler { [weak registrar] call, result in
+      guard call.method == "dismissKeyboard" else {
+        result(FlutterMethodNotImplemented)
+        return
+      }
+      // End editing in this engine's window, including embedded WKWebView fields.
+      registrar?.viewController?.viewIfLoaded?.window?.endEditing(true)
+      // Acknowledge the request; Flutter observes actual view insets.
+      result(nil)
+    }
+  }
+}
+
+/// Measures the current Flutter view's public layout guide instead of keyboard
+/// notification frames, which can be offscreen after an iPad palette transition.
+private final class PybleKeyboardInsets {
+  private weak var registrar: FlutterPluginRegistrar?
+  private let channel: FlutterMethodChannel
+  private var observer: PybleKeyboardGuideView?
+  private var generation: Int?
+  private var lastBottom: CGFloat?
+
+  init(registrar: FlutterPluginRegistrar) {
+    self.registrar = registrar
+    channel = FlutterMethodChannel(
+      name: "dev.pyble/keyboard/insets", binaryMessenger: registrar.messenger())
+    channel.setMethodCallHandler { [weak self] call, result in
+      guard let self = self, let epoch = call.arguments as? Int else {
+        result(FlutterMethodNotImplemented)
+        return
+      }
+      switch call.method {
+      case "observe":
+        self.observe(generation: epoch)
+        result(nil)
+      case "stop":
+        if self.generation == epoch { self.stop() }
+        result(nil)
+      default:
+        result(FlutterMethodNotImplemented)
+      }
+    }
+  }
+
+  private func observe(generation: Int) {
+    if self.generation != generation {
+      stop()
+      self.generation = generation
+    }
+    guard let view = registrar?.viewController?.viewIfLoaded else {
+      observer?.removeFromSuperview()
+      observer = nil
+      publish(0)
+      return
+    }
+    if observer?.superview !== view {
+      observer?.removeFromSuperview()
+      let guideView = PybleKeyboardGuideView()
+      guideView.translatesAutoresizingMaskIntoConstraints = false
+      guideView.isUserInteractionEnabled = false
+      guideView.accessibilityElementsHidden = true
+      guideView.backgroundColor = .clear
+      guideView.changed = { [weak self] bottom in self?.publish(bottom) }
+      observer = guideView
+      view.addSubview(guideView)
+      NSLayoutConstraint.activate([
+        guideView.topAnchor.constraint(equalTo: view.keyboardLayoutGuide.topAnchor),
+        guideView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
+        guideView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+        guideView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+      ])
+      view.layoutIfNeeded()
+    }
+    // An explicit refresh must return a snapshot even if UIKit has not moved:
+    // Dart may have rejected the previous value while its window size lagged.
+    lastBottom = nil
+    observer?.reportOverlap()
+  }
+
+  private func publish(_ bottom: CGFloat) {
+    guard let generation = generation, bottom != lastBottom else { return }
+    lastBottom = bottom
+    channel.invokeMethod("inset", arguments: ["generation": generation, "bottom": bottom])
+  }
+
+  private func stop() {
+    generation = nil
+    observer?.removeFromSuperview()
+    observer = nil
+    lastBottom = nil
+  }
+}
+
+private final class PybleKeyboardGuideView: UIView {
+  var changed: ((CGFloat) -> Void)?
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    reportOverlap()
+  }
+
+  override func didMoveToWindow() {
+    super.didMoveToWindow()
+    reportOverlap()
+  }
+
+  func reportOverlap() {
+    guard let owner = superview, window != nil else {
+      changed?(0)
+      return
+    }
+    // On iOS 15/16 a hidden/undocked guide ends at the safe-area bottom.
+    // A real docked keyboard or input palette reports its full overlap.
+    let overlap = min(owner.bounds.height, max(0, bounds.height))
+    changed?(overlap <= owner.safeAreaInsets.bottom + 0.5 ? 0 : overlap)
   }
 }

app/lib/app/app.dart

@@ -19,6 +19,7 @@ import 'package:pyble/editor/recovery_gate.dart';
 import 'package:pyble/theme/theme.dart';
 
 import 'shell.dart';
+import 'keyboard_insets.dart';
 
 /// Navigator used by explicit user confirmations, never by local recovery itself.
 final GlobalKey<NavigatorState> appNavigatorKey = GlobalKey<NavigatorState>();
@@ -45,6 +46,8 @@ class PybleApp extends StatelessWidget {
       highContrastDarkTheme: PybleTheme.highContrastDark,
       themeMode: ThemeMode.system,
       debugShowCheckedModeBanner: false,
+      builder: (BuildContext context, Widget? child) =>
+          KeyboardInsets(child: child ?? const SizedBox.shrink()),
       home: const RecoveryGate(child: PybleShell()),
     );
   }

app/lib/app/keyboard_dismissal.dart

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Part of PyBLE (https://pyble.dev) — see /LICENSE.
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
+
+const MethodChannel _keyboardChannel = MethodChannel('dev.pyble/keyboard');
+
+/// Requests dismissal of the current window's keyboard, including native
+/// WebView fields. Completion does not assert that the keyboard is hidden;
+/// layout continues to follow the actual view insets.
+Future<void> dismissSoftwareKeyboard() async {
+  if (!kIsWeb &&
+      (defaultTargetPlatform == TargetPlatform.android ||
+          defaultTargetPlatform == TargetPlatform.iOS)) {
+    await _keyboardChannel.invokeMethod<void>('dismissKeyboard');
+  } else {
+    await SystemChannels.textInput.invokeMethod<void>('TextInput.hide');
+  }
+}