Migrate a wizard session saved before the safe-area unit changed

Two more review findings.

The persisted wizard state survives a reload, and SkinModel.load() read
safeTop/safeBottom back verbatim. Those numbers were entered as preview
viewbox units and are now read as points or dp, so a session left by the
older build silently regenerates a different skin: a hand-tuned 40 on a
1080-wide 400ppi Android device meant 135px then and would mean 100px now.
The persisted model carries a schema version, and a session below the
current one takes its insets fresh from the device catalog. There is
nothing to convert back to -- a value tuned by eye was tuned against the
scaling this branch fixes -- and an untouched session got the same numbers
from the catalog anyway. A session with no device selected goes back to the
device step, where resetForDevice refills both values on the way through.
The migration is written back once rather than repeated on every reload.

The documented property example omitted the `cutouts` key the wizard now
writes. A skin rebuilt from that example would paint the opaque island and
give JavaSEPort.parseCutouts() nothing, leaving pointer events free to
reach the content underneath -- exactly the bug the key exists to close.
The example carries the real value for its device (377,53,452,132, checked
against the generator), and the guide's property list and cutouts section
mention it.

Also drops this branch's own fix for the signup-funnel test: master fixed
it in #5628 with an attribute parser rather than a looser regex, which is
the better of the two, so the rebase takes master's version.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: shai-almog

docs/demos/common/src/main/snippets/developer-guide/skin-designer.properties

@@ -17,6 +17,13 @@ displayY=151
 displayWidth=1206
 displayHeight=2622
 
+# The cutouts the skin paints on the screen, as display-relative
+# x,y,w,h rectangles separated by ";". The simulator drops pointer events
+# inside them, so a click on the opaque island cannot reach app content
+# hidden underneath. A skin that omits this key keeps every cutout
+# clickable.
+cutouts=377,53,452,132
+
 # Safe area in display-relative coordinates (origin = screen top-left),
 # in PIXELS. The Info tab's Top/Bottom fields are points (iOS) or dp
 # (Android); the wizard multiplies them by the device's density scale.

docs/developer-guide/Skin-Designer.asciidoc

@@ -123,6 +123,11 @@ pixels. For islands and holes, `Offset Y` is the gap between the
 cutout's top edge and the screen top. For notches, `Offset Y` is
 ignored, because a notch is anchored to the screen's top edge.
 
+The wizard also writes each cutout's rectangle into the `cutouts`
+property. The simulator drops pointer events that land inside one, so a
+click on an opaque notch or island can't reach app content hidden
+underneath it, the way the hardware cutout can't be touched at all.
+
 WARNING: When the wizard generates the `.skin` file, it
 automatically pushes `safePortraitY` down to the lowest cutout edge
 whenever that sits below the platform's own status-bar inset, so app
@@ -170,7 +175,7 @@ Clicking *Finish* in the editor's footer:
   `android_holo_light.res`, or `winTheme.res`) inside the skin zip.
 . Writes `skin.properties` with `roundScreen=true`,
   `displayX/Y/Width/Height`, `safePortrait*` / `safeLandscape*`,
-  the platform name, override names, fonts, and PPI.
+  `cutouts`, the platform name, override names, fonts, and PPI.
 
 Clicking *Download skin* on the done page hands the file to the
 browser's download dialog. The button is the only reliable trigger

scripts/skindesigner/common/src/main/java/com/codename1/tools/skindesigner/SkinDesigner.java

@@ -174,6 +174,11 @@ private void loadState() {
         device = DeviceDatabase.findById(id);
         source = Preferences.get(PREF_SOURCE, null);
         skin.load();
+        if (skin.migrateSafeAreaUnits(device)) {
+            // Write the migrated state straight back, so the conversion
+            // happens once rather than on every reload.
+            skin.save();
+        }
         if (device != null && skin.name == null) {
             skin.resetForDevice(device);
         }

scripts/skindesigner/common/src/main/java/com/codename1/tools/skindesigner/SkinModel.java

@@ -75,6 +75,21 @@ public Cutout(String type, int w, int h, int x, int y, String name) {
 
     private static final String P = "wiz.skin.";
 
+    /**
+     * Layout version of the persisted wizard state.
+     *
+     * <p>1 stored {@link #safeTop} / {@link #safeBottom} in preview viewbox
+     * units, which the generator scaled by {@code resolutionW / 320}. 2
+     * stores them in the density-independent units the device catalog uses
+     * -- points on iOS, dp on Android -- scaled by the device's density.
+     * The numbers look identical in storage and mean different pixel counts,
+     * so a session saved by the older build has to be migrated rather than
+     * loaded; see {@link #migrateSafeAreaUnits}.</p>
+     */
+    private static final int SCHEMA = 2;
+
+    private int schema = SCHEMA;
+
     public void resetForDevice(DeviceDatabase.Device d) {
         presetId = "rr";
         // Drop the trailing " skin" from the generated name — sanitize() then
@@ -105,7 +120,37 @@ public void resetForDevice(DeviceDatabase.Device d) {
         }
     }
 
+    /**
+     * Brings a session persisted by an older build up to {@link #SCHEMA},
+     * and reports whether anything changed so the caller can write it back.
+     *
+     * <p>Schema 1 stored the safe-area insets in viewbox units. Reading one
+     * of those numbers as points would silently regenerate a different skin
+     * from the one the user left behind -- a hand-tuned 40 on a 1080-wide,
+     * 400ppi Android device meant 135px then and would mean 100px now. There
+     * is nothing to convert back to, either: a value the user tuned by eye
+     * was tuned against the scaling this change fixes. So the insets are
+     * taken fresh from the device catalog, which is where an untouched
+     * session got them anyway.</p>
+     *
+     * <p>With no device selected there is nothing to take them from, but the
+     * wizard sends that session back to the device step and
+     * {@link #resetForDevice} refills both values on the way through.</p>
+     */
+    public boolean migrateSafeAreaUnits(DeviceDatabase.Device d) {
+        if (schema >= SCHEMA) {
+            return false;
+        }
+        schema = SCHEMA;
+        if (d != null) {
+            safeTop = d.safeTop;
+            safeBottom = d.safeBottom;
+        }
+        return true;
+    }
+
     public void save() {
+        Preferences.set(P + "schema", SCHEMA);
         Preferences.set(P + "presetId", presetId);
         Preferences.set(P + "name", name);
         Preferences.set(P + "cornerR", cornerR);
@@ -127,6 +172,9 @@ public void save() {
     }
 
     public void load() {
+        // Absent means a session written before the key existed, which is
+        // schema 1 by definition.
+        schema = Preferences.get(P + "schema", 1);
         presetId = Preferences.get(P + "presetId", presetId);
         name = Preferences.get(P + "name", name);
         cornerR = Preferences.get(P + "cornerR", cornerR);
@@ -150,7 +198,7 @@ public void load() {
     }
 
     public static void clearPersisted() {
-        for (String key : new String[]{"presetId", "name", "cornerR", "bezel",
+        for (String key : new String[]{"schema", "presetId", "name", "cornerR", "bezel",
                 "homeIndicator", "safeTop", "safeBottom", "cutoutCount"}) {
             Preferences.delete(P + key);
         }