JavaScript port: real DOM text, incremental semantics, and native-resolution rendering

CodenameOne/src/com/codename1/ui/Dialog.java

@@ -973,6 +973,54 @@ public void removeComponent(Component cmp) {
         dialogContentPane.removeComponent(cmp);
     }
 
+    /// Refreshing the theme reinstalls the menu bar, and installing it moves the form's title
+    /// component into the title area. A dialog's title component is its own title label, and a
+    /// dialog keeps the form title area hidden -- so without putting the label back where it
+    /// belongs, refreshing the theme loses the dialog's title altogether, along with the space
+    /// it occupied in the centered-title layout.
+    ///
+    /// {@inheritDoc}
+    @Override
+    public void refreshTheme(boolean merge) {
+        super.refreshTheme(merge);
+        restoreDisplacedTitle();
+    }
+
+    /// Puts the title label back where this dialog's layout wants it, and touches nothing else.
+    ///
+    /// Rebuilding the whole layout would remove and re-add the content pane, which deinitializes
+    /// that subtree -- taking the form's focus with it when the focused component is in there,
+    /// and closing an editor the user is typing in. Only the label moved, so only the label is
+    /// moved back.
+    private void restoreDisplacedTitle() {
+        Container root = super.getContentPane();
+        Container target = titleCentered ? centeredTitleArea : root;
+        if (target == null) {
+            updateTitleLayout();
+            revalidate();
+            return;
+        }
+        if (titleCentered && centeredTitleArea != null) {
+            // The area's UIID comes from a theme constant, and a refresh is exactly when that
+            // constant can have changed. Restoring the label without it would leave a centered
+            // dialog wearing the previous theme's title styling.
+            centeredTitleArea.setUIID(getUIManager().getThemeConstant(
+                    "dlgCenteredTitleUIID", "Container"));
+        }
+        if (dialogTitle.getParent() == target) { //NOPMD CompareObjectsWithEquals
+            return;
+        }
+        if (dialogTitle.getParent() != null) {
+            dialogTitle.remove();
+        }
+        if (titleCentered) {
+            target.addComponent(BorderLayout.CENTER, dialogTitle);
+        } else {
+            target.addComponent(BorderLayout.NORTH, dialogTitle);
+        }
+        revalidate();
+    }
+
     /// {@inheritDoc}
     @Override
     public Label getTitleComponent() {

CodenameOne/src/com/codename1/ui/Display.java

@@ -1622,12 +1622,14 @@ void setCurrent(final Form newForm, boolean reverse) {
         if (edt == null) {
             throw new IllegalStateException("Initialize must be invoked before setCurrent!");
         }
-
         if (!isEdt()) {
             // when not running callSerially executes synchronously and would recurse here forever (#4811)
             if (!codenameOneRunning) {
                 throw new IllegalStateException("Display.setCurrent must be invoked after Codename One has started running. Call it from start() or via callSerially.");
             }
+            // The direction is not recorded here: this call comes back round on the EDT and
+            // records it there. Doing it in both places would leave one entry behind for a
+            // later navigation to the same form to take.
             callSerially(new RunnableWrapper(newForm, null, reverse));
             return;
         }
@@ -1657,13 +1659,20 @@ void setCurrent(final Form newForm, boolean reverse) {
                 case SHOW_DURING_EDIT_IGNORE:
                     return;
                 case SHOW_DURING_EDIT_SET_AS_NEXT:
+                    newForm.setShownWithReverse(reverse);
                     impl.setCurrentForm(newForm);
                     return;
                 default:
                     break;
             }
         }
 
+        // Recorded once the call is known to be going through: on the EDT, with the form
+        // changing, and past the cases that decline to show anything while text is being
+        // edited. Recording it any earlier would queue a direction that no arrival takes, and a
+        // later navigation to the same form would take that stale one instead of its own.
+        newForm.setShownWithReverse(reverse);
+
         if (current != null) {
             if (current.isInitialized()) {
                 current.deinitializeImpl();
@@ -1713,6 +1722,18 @@ void setCurrent(final Form newForm, boolean reverse) {
                     }
                 }
                 current = current.getPreviousForm();
+                if (current != null) {
+                    // Coming out of a menu back to the form underneath it, which is a backward
+                    // move: without saying so, this arrival takes whatever direction that form
+                    // has left over and a port that keeps browser history in step reads it as a
+                    // step forward, pushing an entry for a form that was already behind.
+                    //
+                    // At the head of the queue, because this arrival comes first: when the form
+                    // being revealed is also the one being shown, its own direction is already
+                    // waiting, and appending would have this restoration take that one and leave
+                    // this one for the show.
+                    current.insertShownWithReverse(true);
+                }
                 impl.setCurrentForm(current);
             }
 

CodenameOne/src/com/codename1/ui/Form.java

@@ -1402,6 +1402,52 @@ Form getPreviousForm() {
         return previousForm;
     }
 
+    /// Directions of the displays asked for on this form that have not arrived yet, oldest
+    /// first. A transition defers a form change, so two navigations to the same form can be in
+    /// flight at once -- showBack() to it, then show() while the first is still animating -- and
+    /// a single field would give both arrivals the direction of the later one.
+    private ArrayList<Boolean> pendingReverse;
+
+    /// The direction of the last arrival, for a form change with nothing queued behind it.
+    private boolean lastShownWithReverse;
+
+    void setShownWithReverse(boolean value) {
+        if (pendingReverse == null) {
+            pendingReverse = new ArrayList<Boolean>();
+        }
+        // Every entry is a display that is going to arrive, so none of them is dropped: a
+        // handful of shows and showBacks can be in flight at once when each is waiting on a
+        // transition, and clearing the queue to make room would hand the first arrival the last
+        // caller's direction. A display that changes nothing -- showing the form already up --
+        // returns before it records anything, so nothing accumulates here unspent.
+        //
+        // The bound is a leak guard rather than a policy: a hundred displays of one form waiting
+        // at once is not navigation, it is something stuck.
+        if (pendingReverse.size() >= 100) {
+            pendingReverse.remove(0);
+        }
+        pendingReverse.add(Boolean.valueOf(value));
+    }
+
+    /// Puts a direction at the head of the queue, for a form change that happens before
+    /// anything already waiting -- a menu folding away to reveal this form, which arrives before
+    /// the show that asked for it.
+    void insertShownWithReverse(boolean value) {
+        if (pendingReverse == null) {
+            pendingReverse = new ArrayList<Boolean>();
+        }
+        pendingReverse.add(0, Boolean.valueOf(value));
+    }
+
+    /// Takes the direction belonging to the form change that is arriving now.
+    boolean consumeShownWithReverse() {
+        if (pendingReverse == null || pendingReverse.isEmpty()) {
+            return lastShownWithReverse;
+        }
+        lastShownWithReverse = pendingReverse.remove(0).booleanValue();
+        return lastShownWithReverse;
+    }
+
     void setPreviousForm(Form previousForm) {
         this.previousForm = previousForm;
     }

Ports/JavaScriptPort/STATUS.md

@@ -17,6 +17,108 @@ routing.
 This document is the handoff for whoever picks up the branch next. Read it
 before you re-attempt switching initializr over.
 
+Web-native overlay layer
+------------------------
+
+The port renders to a canvas, but text, semantics and OS state no longer come
+from it. Two DOM layers sit above the canvas, which is itself marked
+`role=presentation` / `aria-hidden`:
+
+- `#cn1-text-layer` (`JavaScriptTextLayer`) carries the **visible text**.
+  `BufferedGraphics.drawString` -- the display graphics -- hands each run to the
+  layer instead of the canvas, so the text on screen is real DOM text that can be
+  selected, found with the browser's find-in-page, and rasterized by the browser
+  rather than by canvas. Codename One remains the sole layout authority: a run
+  arrives already broken and placed, so it is emitted as one `white-space:pre`
+  element at an absolute coordinate and the browser cannot wrap or reflow it.
+  Text measurement is unchanged and stays on the worker's `OffscreenCanvas`.
+- `#cn1-accessibility-tree` (`JavaScriptSemanticOverlay`) carries the ARIA
+  projection of `AccessibilityTreeSnapshot`. It is updated incrementally --
+  elements are keyed by semantic node id and reused -- because the previous
+  rebuild-per-invalidation discarded DOM focus and text selection on every
+  `CHANGE_BOUNDS`, which is raised by every `setX/setY/setWidth/setHeight`.
+
+The layer takes no pointer events: the canvas owns hit testing, so a drag across
+a label does not start a native selection. Find-in-page, the browser's own text
+handling and assistive technology all reach the text; pointer selection would
+mean teaching the port's input path to tell a selection drag from an application
+drag, which is a change to input rather than to this layer.
+
+Text that stays on the canvas, by design:
+
+- offscreen targets (transition buffers, `paintLock`, `ComponentImage`,
+  `Display.screenshot`) -- they use plain `HTML5Graphics`, so the gate is
+  structural rather than a check;
+- cell renderers, which are one component instance stamped at N positions and so
+  cannot key a pooled element per row;
+- anything outside the displayed form, because the layer sits above the canvas as
+  a whole and nothing painted afterwards can occlude it (a modal dialog paints
+  the form beneath it as its own backdrop);
+- decorated runs -- underline, strike-through, overline -- whose lines are drawn
+  after the glyphs and over them, which a promoted glyph would cover;
+- shape clips and non-identity transforms;
+- anything a later canvas draw covers. The layer is above the canvas as a whole,
+  so an image, fill or shape drawn over a promoted run cannot hide it the way it
+  would have hidden canvas text. Such a run is put back on the canvas and its
+  component stays there -- a sheet's scrim, a tab bar's composited lens, a
+  clipped rotation over a title. Who is drawing decides: a component painting its
+  own background, or a container painting behind children it is about to paint,
+  covers text it draws again a moment later and hides nothing. What the draw
+  reaches decides too: an empty clip or a fully transparent one reaches nothing,
+  the report is clipped to the graphics clip -- to the clip's own outline when it
+  is a shape, since text the clip protects is not covered by a draw it culls --
+  and a shape, polygon, arc, radial gradient or rounded rectangle is asked
+  whether its outline meets the glyphs rather than whether its bounding rectangle
+  does. Curves are walked rather than replaced by their control points.
+
+Bitmap fonts need no exclusion: `Graphics.drawString` renders a `CustomFont`
+itself and never reaches the implementation.
+
+**Consequence for the screenshot suite:** every test in the suite reads the screen
+back to capture it, and a pixel read returns text to the canvas for good -- the
+two representations cannot both be authoritative, and an application that reads
+pixels is saying which one it needs. The goldens are therefore canvas-text at the
+display's real pixel ratio, and have been rebaselined from a CI run. The DOM
+layer is covered by `scripts/verify-javascript-web-overlay.mjs`, which asserts it
+directly instead of through pixels.
+
+Known gaps in this area:
+
+- An editable field is reached through a SET_TEXT control in the actions region rather
+  than by typing into the semantic node itself, which is a div over a canvas. A native
+  input is still what appears once editing starts.
+- Drag-selection is not enabled. The layer takes no pointer events so the canvas
+  keeps hit testing; find-in-page and assistive technology do not need hit
+  testing, but selection does. Enabling it requires the pointer-routing rework.
+- Vertical placement uses `fontHeight()` as the line box, which matches Codename
+  One's own layout metric but is approximate against the browser's font metrics
+  to about a pixel. A text-parity harness comparing `getBoundingClientRect()`
+  against the Codename One width/position is the way to tighten this.
+- Occlusion within a form is not handled; only cross-form occlusion is, along with
+  the glass pane, a dragged component and transitions. A `Sheet`, an
+  `InteractionDialog`, or an opaque sibling in a `LayeredLayout` painting over a
+  text-bearing component will not cover its promoted text, because the layer is
+  above the canvas as a whole. Whether a later sibling covers an earlier one is
+  not known at the time the earlier one paints, so the only general answer is to
+  promote the covering content too -- which is the DOM renderer this deliberately
+  is not.
+
+Main-thread browser state
+-------------------------
+
+Several features were written when the port ran on the main thread and silently
+did nothing once it moved into a worker, because the objects they reach for do
+not exist there. `history.pushState` was a `@JSBody` and threw on every form
+change (the port logged that the back command would not work), and every
+`matchMedia` query -- dark mode, reduced motion, forced colors, contrast,
+reduced transparency -- answered `false` unconditionally. Both now go through
+the host bindings so they run on the main thread; media query results are cached
+and refreshed from a `change` listener.
+
+The rule this illustrates is worth keeping in mind for any future port work:
+**a `@JSBody` runs in the worker.** Anything touching `window`, `document`,
+`history`, `matchMedia` or `navigator` has to go through a host binding instead.
+
 Build
 -----
 

Ports/JavaScriptPort/src/main/java/com/codename1/html5/js/browser/MediaQueryList.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.html5.js.browser;
+
+import com.codename1.html5.js.JSObject;
+
+/**
+ * Interface for the JavaScript MediaQueryList object.
+ * https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList
+ */
+public interface MediaQueryList extends JSObject {
+    boolean getMatches();
+    String getMedia();
+    void addEventListener(String type, Object listener);
+    void removeEventListener(String type, Object listener);
+}

Ports/JavaScriptPort/src/main/java/com/codename1/html5/js/browser/Window.java

@@ -33,6 +33,24 @@
  * https://developer.mozilla.org/en-US/docs/Web/API/Window
  */
 public interface Window extends JSObject {
+    /**
+     * Evaluates a CSS media query on the main thread. The worker has no matchMedia, so every
+     * OS-level preference -- dark mode, reduced motion, forced colors -- has to be read through
+     * this binding rather than from worker script.
+     *
+     * @param query the media query text
+     * @return the live query list, or null where the browser does not support matchMedia
+     */
+    MediaQueryList matchMedia(String query);
+
+    /**
+     * The display's scale factor, read from the main thread. The worker's copy is forwarded
+     * once at start-up and does not follow zoom or a move between displays.
+     *
+     * @return devicePixelRatio
+     */
+    double getDevicePixelRatio();
+
     static Window current() {
         return null; // Native implementation
     }

Ports/JavaScriptPort/src/main/java/com/codename1/html5/js/dom/PopStateEvent.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2026, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.html5.js.dom;
+
+/**
+ * Interface for the JavaScript PopStateEvent object.
+ * https://developer.mozilla.org/en-US/docs/Web/API/PopStateEvent
+ *
+ * <p>The state is read because popstate fires for forward traversal as well as backward, and
+ * the two are only distinguishable by comparing the state the browser restored against the one
+ * currently displayed. It is typed as Object rather than String: history state is any
+ * structured-cloneable value, and a page that embeds this canvas may keep its router's own
+ * object there. Binding it as a String would put that entry through a conversion it cannot
+ * satisfy, when all the port needs is to see that the value is not one of its own.</p>
+ */
+public interface PopStateEvent extends Event {
+    Object getState();
+}