buninu-browser 0.4.0 → 0.5.1

package/lib/qml/README.md

@@ -969,3 +969,459 @@ remain in Flea's thumbnail cache until invalidated or removed.
 媒體資訊。官方 0.3.12 後端已實測接受並寫入縮圖快取，沿用實驗容器的
 bwrap 繞過路徑，無須修改 Flea QML。刪除註冊檔可停用，但既有佔位縮圖
 仍保留在快取，直到失效或被移除。
+
+## Omastorm container
+
+### Android / Termux setup
+
+Termux's terminal does not support Kitty graphics. Start Land inside jsgotty's
+browser terminal instead; keep container build commands in a separate native
+Termux shell. These steps are self-contained and do not require the Flea setup.
+
+1. **Install Bun and start jsgotty in native Termux**:
+
+   ```sh
+   npm i -g bun
+   bun --version
+   bunx jsgotty -w -r --session bash
+   ```
+
+   Open the complete URL printed by jsgotty in your phone's browser or WebView.
+   `-w` permits terminal input, `-r` generates that random URL, and `--session`
+   keeps the shell available for reconnection. This server-side `-r` is different
+   from the CLI client's `--client -r PID`.
+
+   For on-screen Super, Alt and Ctrl keys, you can first build a minapk app:
+
+   ```sh
+   npx @drxiaozhi/minapk
+   ```
+
+   Install and open the generated APK. Inside the app, press **Volume Up**,
+   choose **Go to URL**, and enter the complete jsgotty URL. Use the app's
+   modifier keys for shortcuts; **long-press Alt to activate Super**.
+
+2. **Start Land inside that browser terminal** and leave it running:
+
+   ```sh
+   env XDG_RUNTIME_DIR="$TMPDIR" bunx buninu-land
+   ```
+
+   The first launch may download Land and Casty. Its display stays in the browser
+   terminal; the default socket is `$TMPDIR/wayland-buninu`. Use that default
+   socket for the commands below. An existing Land instance can cause a numbered
+   name such as `wayland-buninu1`; check the address shown by Land.
+
+3. **Open another native Termux shell and install js-udocker**. Do not run these
+   commands in Land's address bar or inside a Debian proot. Skip package
+   installation if these tools are already installed:
+
+   ```sh
+   pkg install git nodejs proot curl tar
+   cd "$HOME"
+   git clone https://github.com/jjtseng93/js-udocker.git
+   cd js-udocker
+   sh termux_install.sh
+   hash -r
+   command -v udocker
+   ```
+
+   The installer points `udocker` at this checkout and uses Node.js and proot.
+   Keep the checkout in place. If js-udocker is already installed, reuse it.
+
+4. **Get buninu-browser as the build context**, still in the second shell.
+   Reuse your checkout if it already contains this Dockerfile:
+
+   ```sh
+   cd "$HOME"
+   git clone https://github.com/jjtseng93/buninu-browser.git
+   cd buninu-browser
+   test -f test/fixtures/omastorm-helpers/Dockerfile
+   test -S "$TMPDIR/wayland-buninu"
+   ```
+
+   No `bun install` is needed in the checkout. A socket file alone does not prove
+   Land is still running: `ECONNREFUSED` means you must restart Land.
+
+5. **Build and run from the repository root**:
+
+   ```sh
+   udocker build -t omastorm-qml -y -f test/fixtures/omastorm-helpers/Dockerfile .
+   udocker run -b "$TMPDIR:/tmp" omastorm-qml
+   ```
+
+   Return to the browser terminal to use Omastorm. The bind exposes the host's
+   Land socket at `/tmp/wayland-buninu`; no extra startup arguments or font
+   environment variables are needed. Do not start another Land inside the
+   container. If deliberately using a numbered socket, pass
+   `-e WAYLAND_DISPLAY=/tmp/wayland-buninu1` before `omastorm-qml` in the run
+   command instead.
+
+### Linux Docker
+
+Start `bunx buninu-land` on the host in a terminal supporting Kitty graphics.
+Then build from the buninu-browser repository root in another shell:
+
+```sh
+docker build -t omastorm-qml -f test/fixtures/omastorm-helpers/Dockerfile .
+docker run --rm -v "${XDG_RUNTIME_DIR:-/tmp}:/tmp" omastorm-qml
+```
+
+The mounted directory must contain the running Land socket named
+`wayland-buninu`, and the container user must be able to connect to it.
+Docker's `--rm` removes container settings after exit; arrange persistent
+storage separately if needed.
+
+### Image contents and validation
+
+The following explains the image and its checks; no additional manual
+installation is needed after the steps above.
+
+- [Dockerfile](../../test/fixtures/omastorm-helpers/Dockerfile) uses `oven/bun:1.4.4`,
+  single-stage COPY/RUN, one `ENV KEY=value` per line and JSON CMD, matching the
+  Flea recipe and js-udocker parser.
+- It downloads Omastorm revision `492e97841146bd9d6d9f7a3064e5e1ae9840cc68`
+  (manifest 0.1.23) and the official engine 0.1.15 via upstream's pinned release
+  installer and checksums, for aarch64 or x86_64. Rust compilation is not needed.
+- It downloads JetBrainsMono Nerd Font Mono Regular from Nerd Fonts v3.4.0,
+  including its OFL license, and sets `QT_QPA_FONTDIR` inside the image.
+- Browser code and its existing WASM/fonts are copied from the build context;
+  no npm dependencies are installed into your checkout. Rebuild after changing
+  browser code. Native Qt, Quickshell, Mesa and GPU device access are unnecessary.
+- [prepare.mjs](../../test/fixtures/omastorm-helpers/prepare.mjs) removes only the
+  two explicit Software-backend refusal checks in this container's Omastorm UI.
+  It saves `.upstream` originals and refuses unexpected source changes. Actual
+  shader compilation and texture verification remain enabled; this is the same
+  experimental software path as the manual Omastorm demonstration.
+- [launch.mjs](../../test/fixtures/omastorm-helpers/launch.mjs) starts an owned
+  engine in a unique temporary runtime directory, then opens the QML frontend.
+  It keeps the Land socket at its original absolute path, so sharing `/tmp`
+  does not reuse or stop another Omastorm engine. Closing the window or stopping
+  the launcher closes its engine and removes its temporary textures/socket.
+- [check.mjs](../../test/fixtures/omastorm-helpers/check.mjs) runs during build:
+  verifies Bun version, the official engine executable, all four software
+  shaders, Nerd Font glyph coverage and a QML screenshot. It needs no Land or
+  weather downloads. Require the final `PASS:` message; js-udocker versions
+  which continue after failed RUN steps may still report overall success.
+- After binding `/tmp`, verify the real engine Unix-socket hello/site list with
+  `udocker run -b "$TMPDIR:/tmp" omastorm-qml bun /usr/local/lib/omastorm-helpers/check.mjs --engine`.
+  This is separate because js-udocker's unbound build ROOT/tmp path can exceed
+  the Unix socket path-length limit. The normal launcher also waits for its
+  engine socket before opening QML.
+- Live radar/map data still needs network access and a selected station. A fresh
+  profile may ask for a location; use the application's picker. Build checks do
+  not promise available live weather, full native-QML parity or GPU performance.
+
+## Omastorm compatibility experiments
+
+The first compatibility stage provides local `Quickshell.Io.Socket` with Unix
+socket connections, UTF-8 `SplitParser` messages, writes, disconnect/reconnect,
+and document-owned cleanup. `connected` reads the actual connection state;
+assigning it requests a connection/disconnection. Writes are queued immediately;
+`flush()` is accepted without adding a second buffer. This does not expose host
+sockets to ordinary HTML or remote QML.
+
+QML `Canvas` reuses the browser's HTML canvas and 2D context. The adapter supplies
+paint scheduling, dimensions, QML color conversion, reset, and cancellation when
+disposed. It currently supports `requestPaint`, `markDirty` (full repaint),
+`contextType: "2d"`, and animation callbacks. QML image-loading extensions,
+canvas tiling and alternate render strategies remain unsupported. Software
+`ShaderEffect` and image-loading support are described in the later experiment
+sections. `QtQuick.Window` imports resolve existing Window attached behavior;
+this does not implement every type from that module.
+
+To probe an existing official Omastorm engine using the unmodified `Engine.qml`:
+
+```sh
+env XDG_RUNTIME_DIR=/tmp bun test/manual-omastorm-engine.mjs /path/to/omastorm
+```
+
+The probe does not download or start the engine. This stage has received the
+real engine's site list and polar-frame state, and rendered `RadarMark.qml`.
+That initial milestone has since progressed to the experimental software radar
+window described above; it does not imply full native Quickshell compatibility.
+
+### Omastorm 相容性實驗
+
+第一階段加入本地 `Quickshell.Io.Socket`：Unix socket 連線、UTF-8
+`SplitParser` 訊息、寫入、斷線重連，以及頁面關閉時清理。`connected` 讀取實際
+連線狀態，賦值則要求連線／斷線；寫入立即排入傳輸，`flush()` 不另建緩衝。
+一般 HTML 與遠端 QML 不會因此取得 host socket 能力。
+
+QML `Canvas` 重用瀏覽器的 HTML canvas／2D context，只轉接重繪排程、尺寸、
+QML 顏色、reset 與銷毀清理。目前支援 `requestPaint`、`markDirty`（整張重繪）、
+`contextType: "2d"` 與動畫回呼；QML 圖片載入擴充、畫布分塊、其他渲染策略與
+自訂 `ShaderEffect` 已有實驗性軟體子集，詳見後段說明。`QtQuick.Window` import 可使用既有 Window
+附加行為，不代表該模組所有類型皆已實作。
+
+上方命令可使用未修改的 `Engine.qml` 連到已啟動的官方後端，不會下載或啟動後端。
+已實測收到站點清單與 polar frame 狀態，並渲染原版 `RadarMark.qml`；完整 shell
+已由此初期成果推進到後段的軟體雷達實驗，詳見下方 ShaderEffect 與 Omastorm 軟體版應用說明；仍不代表完整相容。
+
+### Keyboard shortcuts and object delegates
+
+`Shortcut` supports string `sequence`/`sequences`, portable key names,
+Ctrl/Alt/Shift/Meta modifiers, up to four key strokes (one-second prefix timeout),
+enabled/autoRepeat, and activated/activatedAmbiguously signals. It consumes
+matching DOM keydown events before ordinary key handlers. Window scope uses the
+existing QML window/focus state; ApplicationShortcut applies across the document's
+windows. Native text currently uses portable text. Numeric StandardKey bindings,
+platform-localized key names and Keys.shortcutOverride are not implemented.
+
+`Instantiator` reuses Repeater's scoped factories for synchronous array/count
+models. Objects are parented to the Instantiator; active, count, object/objectAt,
+objectAdded/objectRemoved, model replacement and disposal are supported. Dynamic
+delegate replacement and richer model adapters remain unsupported; asynchronous
+creation is rejected explicitly. As with Repeater, a model replacement currently
+recreates all delegates rather than preserving identities by row diff.
+
+### 快捷鍵與物件委派
+
+`Shortcut` 支援字串 sequence／sequences、可攜式鍵名、Ctrl／Alt／Shift／Meta、
+最多四段按鍵（前綴等待一秒）、enabled／autoRepeat，以及 activated／
+activatedAmbiguously。透過 DOM keydown 攔截匹配按鍵，視窗範圍沿用既有 QML 焦點
+狀態。nativeText 暫用 portableText；數字 StandardKey、平台翻譯鍵名與
+Keys.shortcutOverride 尚未支援。
+
+`Instantiator` 重用 Repeater 的作用域工廠，同步建立陣列／數量模型的物件。
+支援正確父物件、active、count、object／objectAt、增加／移除訊號、模型替換與
+銷毀清理。動態 delegate 替換及其他模型轉接尚未支援，非同步建立會明確報錯。
+目前模型替換會重建所有委派，尚未以逐列差異保留物件身分。
+
+`PathMultiline` now emits independent SVG subpaths; the existing canvas ShapePath
+fallback also accepts the same geometry. `GridLayout` supports sequential
+row-major placement with columns/rows, spacing, preferred/minimum sizes,
+fill/alignment and implicit dimensions. Explicit cell coordinates, spans,
+right-to-left flow and uniform-cell options are not implemented. Nested layouts
+retain intrinsic preferred dimensions instead of feeding allocated widths back
+into the parent. The original Omastorm KeysSheet has been screenshot-checked with
+both columns visible; this does not validate the shader-dependent radar window.
+
+`PathMultiline` 已接到 SVG 子路徑，既有 canvas ShapePath 路徑也接受同一份幾何。
+`GridLayout` 支援逐列排列、欄列數、間距、偏好／最小尺寸、填滿／對齊與自然尺寸；
+指定格位、跨格、由右至左及等寬格選項尚未支援。巢狀 Layout 不再把父層分配的
+寬度反灌成自然寬度。已截圖確認原版 KeysSheet 雙欄正常，但不代表雷達視窗已可用。
+
+### Experimental software ShaderEffect
+
+`shader/fragment.js` experimentally translates a Qt-style GLSL fragment subset
+to SkSL and compiles it with the existing CanvasKit RuntimeEffect. CPU raster
+surfaces execute it without EGL, Vulkan, WebGL, new native libraries or a second
+production CanvasKit instance. The caller supplies existing child shaders and
+uniforms; the drawing path does not encode images or read pixels back into JS.
+Only tests read pixels to verify results.
+
+```sh
+bun test test/qml-software-shader.test.js
+bun test/manual-omastorm-shaders.mjs /path/to/omastorm
+```
+
+The offline manual probe compiles all four upstream `.frag.qsb` packages and checks
+known pixels for tile and texture-check. Radar/grid compilation is **not** a
+visual correctness or performance result. The current translator supports one
+vec4 output, qt_TexCoord0, simple uniform blocks, scalar/vector/matrix uniforms,
+2D child sampling and level-zero textureSize. It is not a complete GLSL compiler;
+preprocessing, custom vertex shaders and additional interfaces are unsupported.
+Native shader compilation errors remain errors, never successful placeholders.
+
+Local QML ShaderEffect now accepts raw GLSL or QSB v9 desktop GLSL records.
+Numeric/vector/color uniforms update reactively; Image and ShaderEffectSource
+samplers reuse renderer images, and output goes directly into an HTML canvas.
+Resources are disposed on item destruction or page teardown. No PNG encoding,
+base64 or JS pixel readback is introduced in the rendering path.
+
+Run the self-contained clickable gradient with:
+
+```sh
+bun lib/qml/qswayland -p test/fixtures/qml-shader/main.qml
+```
+
+An original Omastorm tile QSB and cached map texture have rendered on CPU.
+A patched application copy now displays a polar RadarMap; large mosaic
+TextureCheck and complete UI compatibility are not yet verified. Custom
+vertex shaders, mesh/culling changes, full GLSL and other QSB versions remain
+unsupported. GPU acceleration remains optional future work.
+
+### 實驗性純軟體 ShaderEffect
+
+`shader/fragment.js` 實驗性地把 Qt 風格 GLSL fragment 子集轉成 SkSL，重用現有
+CanvasKit RuntimeEffect，在 CPU raster surface 執行，不需要 EGL、Vulkan、
+WebGL 或新的原生依賴。材質由同一個 CanvasKit 的 child shader 提供，繪製本身
+不做圖片編碼或像素讀回；測試才讀回像素驗證。
+
+上方離線實驗已編譯原版四份 `.frag.qsb`，並驗證 tile／texture-check 的已知像素。
+radar 已在完整介面顯示極座標回波；grid 仍只有編譯驗證，尚未確認大型拼接圖。轉譯器僅支援
+單一 vec4 輸出、qt_TexCoord0、簡單 uniform block、數值／向量／矩陣 uniform、
+二維材質取樣及第零層 textureSize，不是完整 GLSL 編譯器。
+
+本地 QML 已接上 QSB v9 的桌面 GLSL、數值／向量／色彩 uniform、Image 與
+ShaderEffectSource 材質，以及重繪與資源釋放。輸出直接寫入既有 HTML canvas，
+沒有增加 PNG、base64 或 JS 像素讀回。上方命令可開啟點擊換色的獨立示範。
+已用原版 Omastorm 地圖與雷達 QSB 確認 CPU 繪圖；大型拼接圖的
+TextureCheck 與全部 UI 行為尚未驗證。自訂 vertex shader、mesh／culling、完整 GLSL 與其他
+QSB 版本仍未支援。純軟體是必要路徑，GPU 僅作未來可選加速。
+
+### Item capture and Canvas image reads
+
+Local QML items support `grabToImage(callback, size)` using the existing DOM
+snapshot and HTML canvas path. The result exposes a PNG data URL; encoding is
+performed only for an explicit grab, never for each ShaderEffect frame.
+Canvas supports `loadImage`, `unloadImage`, `isImageLoaded`, `isImageLoading`,
+`isImageError`, `imageLoaded`, and the `createImageData(url)` image-read overload.
+Pending captures are cancelled on item destruction. `saveToFile` is not yet
+implemented. A sampler-size shader → 16×16 grab → Canvas image read integration
+test verifies green pixels for the actual 2×3 source texture, without a GPU.
+
+The original Omastorm application still explicitly rejects `GraphicsInfo.Software`;
+software shader support alone cannot bypass that application policy. The explicit
+test-copy procedure below removes those policy checks without faking a backend.
+
+### Item 擷取與 Canvas 圖片讀取
+
+本地 QML Item 的 `grabToImage(callback, size)` 重用既有 DOM snapshot 與 HTML
+canvas，回傳 PNG data URL。只有明確擷取才編碼，不增加每幀 ShaderEffect 的成本。
+Canvas 已支援載入、卸載、載入狀態查詢、`imageLoaded` 及
+`createImageData(url)` 讀取圖片。Item 銷毀會取消待執行擷取；`saveToFile` 尚未實作。
+整合測試已驗證「材質尺寸 shader → 16×16 擷取 → Canvas 讀取」取得正確綠色像素，
+確認原始 2×3 材質尺寸，完全不需要 GPU。
+
+Omastorm 原版仍明確拒絕 `GraphicsInfo.Software`，這是應用自己的限制，不能只靠
+軟體 shader 支援解除。下方明確修改測試副本的做法會移除這兩處政策限制，
+沒有假報繪圖後端。
+
+
+### Omastorm software application experiment
+
+With the official engine already running and Land available through
+`WAYLAND_DISPLAY` / `XDG_RUNTIME_DIR`:
+
+```sh
+bun test/manual-omastorm-software.mjs ../omastorm
+```
+
+The script prints a new temporary directory, copies only the UI, and removes
+the two explicit `GraphicsInfo.Software` rejection branches. It leaves the
+checkout, native shaders, texture-size verification and minimum window size
+unchanged. `--prepare-only` creates the copy without opening a window.
+
+The browser now supplies Button content/background/padding/focus handling,
+attached Window changes, ListModel required delegate roles, locale/date helpers,
+and size/vector defaults. `FloatingWindow.minimumSize` and `maximumSize` affect
+QML geometry and are sent as xdg_toplevel size hints by the Wayland frontend.
+Only one frontend toplevel is currently represented; independent native windows
+and all Qt Control styling semantics are not claimed. Rectangle antialiasing
+uses the existing CSS/CanvasKit raster policy (disabling it is not implemented).
+
+Nested Loader startup no longer loses pending outer change handlers. Imperative
+`createObject` initialization no longer adds child-state dependencies to its
+calling binding, which previously could recreate sockets repeatedly.
+
+The full UI has displayed cached KMUX polar radar echoes, map tiles and place
+labels using software rendering. Missing icon glyphs, rendering cost, custom
+cursor visuals, mosaic grids and the full set of interactions still need work.
+This is an experiment, not complete Omastorm compatibility.
+
+### Omastorm 軟體版應用實驗
+
+先啟動官方引擎及 Land，設定 `WAYLAND_DISPLAY`／`XDG_RUNTIME_DIR`，再執行上方
+命令。腳本會印出新的暫存目錄，只複製 UI、移除兩處 Software 拒絕判斷，不修改
+checkout、shader、材質尺寸驗證或最小視窗尺寸。`--prepare-only` 只建立副本。
+
+已補 Button 的內容、背景、padding 與焦點，Window 附加通知、ListModel 必填角色、
+地區／日期格式及 size／向量初值。`minimumSize`／`maximumSize` 除了約束 QML
+幾何，也會傳送 Wayland 尺寸提示。目前 frontend 仍只有單一原生 toplevel，
+不是完整多視窗或全部 Qt Controls 樣式相容。Rectangle 抗鋸齒沿用現有 renderer，
+尚未實作關閉抗鋸齒。
+
+已修正巢狀 Loader 啟動遺失外層變更通知，以及 `createObject` 建立過程污染呼叫方
+binding 依賴、造成 Socket 重建的問題。完整介面已用軟體顯示 KMUX 極座標雷達
+回波、地圖與地名；圖示缺字、繪製成本、自訂游標視覺、拼接圖及全部互動仍待驗證。
+
+### Local fallback fonts / 本機備用字型
+
+Local QML documents in host mode accept `QT_QPA_FONTDIR`. It names **one
+folder**, as in Qt; colon/semicolon-separated folder lists are not supported.
+This implementation additionally searches subfolders and follows symlinks with
+cycle/duplicate protection. Put fonts from several sources under one folder
+(or link their folders into it).
+
+```sh
+env QT_QPA_FONTDIR=/path/to/fonts \
+  bun index.js --quickshell-wayland -p /path/to/shell.qml
+```
+
+Supported files are `.ttf` and `.otf`. Fonts are decoded once on the first local
+QML navigation per renderer process, then reused; there is no per-frame scan or
+automatic download. Existing fonts remain first, and the discovered fonts supply
+missing glyphs to both Text and Canvas. Regular faces are ordered before other
+faces. Explicit family names are also recognized, but complete Qt font style
+matching is not implemented. Private-use icon codepoints require the appropriate
+icon font (for example Nerd Font); another font may use the same codepoint for a
+different symbol.
+
+The directory is read from the environment at process startup. Restart after
+changing its contents. No variable means no extra font scan. Ordinary HTML pages
+retain their existing fonts, including after navigation away from QML. Invalid
+fonts are reported and skipped. Loading is bounded to 32 MiB per file, 128 MiB
+total, 128 decoded faces, 4096 visited paths and 16 directory levels. Font
+collections (`.ttc`), Fontconfig rules and automatic system discovery are not
+implemented here.
+
+本機 QML 的 host 模式支援 `QT_QPA_FONTDIR`，與 Qt 一樣指定**單一目錄**，
+不接受冒號或分號分隔的多目錄清單。我們另外支援遞迴子目錄及符號連結，會避免
+循環和重複；多個字型來源可以放在同一目錄下，或把它們的目錄連結進去。
+
+支援 `.ttf`、`.otf`，每個 renderer 程序首次載入本機 QML 時解碼一次並重用，
+不會每幀掃描或自動下載。原有字型優先，缺字才使用找到的字型，Text 與 Canvas
+共用。Regular 字型排在其他樣式之前，也支援直接指定找到的 family 名稱，但尚未
+完整實作 Qt 的字重／樣式匹配。私用區圖示需使用正確的圖示字型（例如 Nerd Font）；
+另一套字型在同一碼位可能是不同圖案。
+
+環境變數在程序啟動時讀取，修改目錄內容後請重啟。未設定就不額外掃描；一般 HTML
+維持原本字型，即使從 QML 導航回 HTML 也一樣。損壞字型會回報並跳過。上限為每檔
+32 MiB、合計 128 MiB、128 個解碼字型、4096 個路徑與 16 層目錄。此功能尚不支援
+`.ttc` 字型集合、Fontconfig 規則或自動搜尋系統字型。
+
+Manual Text/Canvas icon check / 手動檢查文字及 Canvas 圖示：
+
+```sh
+env QT_QPA_FONTDIR=/path/to/nerd-fonts \
+  bun index.js --quickshell-wayland -p test/fixtures/qml-fonts/main.qml
+```
+
+### System locale / 系統地區設定
+
+Local host-mode QML reads `LC_ALL`, then the relevant category (`LC_TIME`,
+`LC_MEASUREMENT`, or `LC_MESSAGES`), then `LANG`. Empty values are ignored.
+`C`, `C.UTF-8` and `POSIX` use the Qt C locale: metric units, day-first short
+ dates and 24-hour time. Explicit `Qt.locale("en_US")` overrides the system
+categories; Unix names such as `en_US.UTF-8` are accepted. Unsupported locale
+names fall back to C. The environment is captured at process startup.
+Non-C format data and timezone labels still use JavaScript Intl, so exact
+punctuation or timezone abbreviations may differ from Qt's locale database.
+This does not change ordinary web-page Intl behavior.
+
+本機 host 模式的 QML 依序採用 `LC_ALL`、對應分類（`LC_TIME`、
+`LC_MEASUREMENT` 或 `LC_MESSAGES`）、`LANG`，空值跳過。
+`C`、`C.UTF-8` 和 `POSIX` 採 Qt 的 C locale：公制、日優先的短日期與
+24 小時制。明確指定 `Qt.locale("en_US")` 時不受系統分類設定影響，也接受
+`en_US.UTF-8` 形式；不支援的名稱退回 C。環境設定在程序啟動時保存。
+非 C 的格式資料及時區名稱仍使用 JavaScript Intl，因此標點或時區縮寫可能與
+Qt 資料庫不同。一般網頁的 Intl 行為不受影響。
+
+### Pointer actions and synchronous notifications / 滑鼠操作與同步通知
+
+QML MouseArea and TapHandler now receive accepted right/middle clicks through
+both CDP/Casty and the Wayland frontend; double clicks also reach their handlers.
+Property `Changed.connect(...)` notifications run synchronously after binding
+invalidation, allowing callers to read mirrored state immediately. Ordinary
+rendering effects remain batched. This fixes Flea's Duplicate validation reading
+an obsolete zero selection count after its menu closes; it does not bypass the
+application's permission or selection checks. `Window.window.update()` requests
+a frame through the existing renderer; it does not create a separate render loop.
+
+QML MouseArea／TapHandler 可從 CDP／Casty 與 Wayland 收到允許的右／中鍵，
+雙擊也會傳給對應 handler。屬性的 `Changed.connect(...)` 在 binding 失效後同步
+通知，讓呼叫端立刻讀到同步後的狀態；一般畫面更新仍批次處理。這修復 Flea
+關閉選單後 Duplicate 驗證讀到舊的零選取數量，沒有跳過權限或選取檢查。
+`Window.window.update()` 透過既有 renderer 要求重繪，不另開繪圖迴圈。

package/lib/qml/builtins.js

@@ -27,7 +27,7 @@ export const nonvisualTypes = new Set([
   'Component',
   'Scale',
   'Translate',
-  'Repeater',
+  'Shortcut', 'Instantiator', 'Repeater',
   'TapHandler',
   'HoverHandler',
   'QtObject',
@@ -35,6 +35,7 @@ export const nonvisualTypes = new Set([
   'Timer',
   'Connections',
   'FileView',
+  'Socket',
   'Process',
   'StdioCollector',
   'SplitParser',
@@ -42,6 +43,8 @@ export const nonvisualTypes = new Set([
   'FontMetrics',
 ]);
 export const typeProperties = {
+  FloatingWindow:['minimumSize','maximumSize'],
+  Button:['padding','contentItem','background','focusPolicy','hovered','pressed','down'],
   MediaPlayer:['source','autoPlay','audioOutput','videoOutput','position','duration','playbackState','playing','mediaStatus','error','errorString','hasAudio','hasVideo','seekable','bufferProgress','loops','play','pause','stop'],
   AudioOutput:['muted','volume'],
   VideoOutput:['fillMode','sourceRect','contentRect'],
@@ -262,7 +265,7 @@ export const typeProperties = {
     'font',
     'color',
     'cursorPosition',
-    'cursorVisible',
+    'cursorVisible','cursorDelegate',
     'selectionStart',
     'selectionEnd',
     'selectedText',
@@ -294,7 +297,7 @@ export const typeProperties = {
     'font',
     'color',
     'cursorPosition',
-    'cursorVisible',
+    'cursorVisible','cursorDelegate',
     'selectionStart',
     'selectionEnd',
     'selectedText',
@@ -360,7 +363,9 @@ export const typeProperties = {
   Scale: ['xScale', 'yScale', 'origin'],
   Translate: ['x', 'y'],
   Shape: ['preferredRendererType', 'transform'],
-  ShaderEffectSource: ['sourceItem', 'sourceRect', 'textureSize', 'hideSource', 'live', 'scheduleUpdate', 'scheduledUpdateCompleted'],
+  Canvas: ['loadImage','unloadImage','isImageLoaded','isImageLoading','isImageError','imageLoaded','available','contextType','context','canvasSize','getContext','requestPaint','markDirty','paint','painted','requestAnimationFrame','cancelRequestAnimationFrame'],
+  ShaderEffect: ['fragmentShader','vertexShader','status','log','blending','cullMode'],
+  ShaderEffectSource: ['mipmap','sourceItem', 'sourceRect', 'textureSize', 'hideSource', 'live', 'scheduleUpdate', 'scheduledUpdateCompleted'],
   ShapePath: [
     'fillItem',
     'fillGradient',
@@ -379,8 +384,12 @@ export const typeProperties = {
   Flow: ['flow', 'spacing', 'layoutDirection'],
   RowLayout: ['spacing', 'layoutDirection', 'uniformCellSizes'],
   ColumnLayout: ['spacing', 'uniformCellSizes'],
+  GridLayout: ['columns','rows','rowSpacing','columnSpacing'],
+  PathMultiline: ['paths'],
   Grid: ['columns', 'rows', 'spacing', 'rowSpacing', 'columnSpacing'],
 
+  Shortcut: ['sequence','sequences','enabled','autoRepeat','context','portableText','nativeText','activated','activatedAmbiguously'],
+  Instantiator: ['model','delegate','count','active','asynchronous','object','objectAt','objectAdded','objectRemoved'],
   Repeater: ['model', 'delegate', 'count', 'itemAt'],
   MouseArea: [
     'acceptedButtons',
@@ -432,6 +441,7 @@ export const typeProperties = {
     'fileChanged',
     'loadFailed',
   ],
+  Socket: ['path', 'connected', 'parser', 'write', 'flush', 'error'],
   Process: [
     'running',
     'command',
@@ -477,7 +487,12 @@ for (const type of ['ListView', 'GridView'])
   typeProperties[type].push(...typeProperties.Flickable);
 
 // Serialized into the page together with the reactive runtime.
-export function createQt() {
+export function createQt(localeEnvironment = null) {
+  // Only local QML has the host capability. Never expose process.env to a
+  // sandboxed page; accept an explicit snapshot for deterministic tests.
+  const localeEnv = localeEnvironment ?? Object.fromEntries(
+    ['LC_ALL','LC_MESSAGES','LC_TIME','LC_MEASUREMENT','LANG'].map(key =>
+      [key, globalThis.__qmlHost?.env(key) || '']));
   const bindingValues = new WeakMap();
   const clamp = (x) => Math.max(0, Math.min(1, Number(x)));
   function rgba(r, g, b, a = 1) {
@@ -607,7 +622,60 @@ export function createQt() {
   for (let i = 0; i < 26; i++) keys[String.fromCharCode(65 + i)] = 65 + i;
   for (let i = 0; i < 10; i++) keys[String(i)] = 48 + i;
   for (let i = 1; i <= 35; i++) keys['F' + i] = 0x01000030 + i - 1;
+  function localeTag(name) {
+    const raw = String(name || 'C');
+    const base = raw.split('.')[0].split('@')[0];
+    if (/^(C|POSIX)$/i.test(base)) return 'C';
+    try {
+      const tag = Intl.getCanonicalLocales(base.replaceAll('_','-'))[0];
+      return Intl.DateTimeFormat.supportedLocalesOf([tag]).length ? tag : 'C';
+    } catch { return 'C'; }
+  }
+  function systemLocale(category) {
+    return localeTag(localeEnv.LC_ALL || localeEnv[category] || localeEnv.LANG || 'C');
+  }
+  function locale(name) {
+    const explicit = name !== undefined && name !== '';
+    const actual = explicit ? localeTag(name) : systemLocale('LC_MESSAGES');
+    const timeLocale = explicit ? actual : systemLocale('LC_TIME');
+    const measurement = explicit ? actual : systemLocale('LC_MEASUREMENT');
+    const region = measurement === 'C' ? '' : new Intl.Locale(measurement).maximize().region;
+    const pattern = (time, short) => {
+      if (timeLocale === 'C') return time ? (short ? 'HH:mm' : 'HH:mm:ss t')
+        : (short ? 'd MM yyyy' : 'dddd, d MMMM yyyy');
+      const formatter = new Intl.DateTimeFormat(timeLocale, time
+        ? {hour:'numeric',minute:'2-digit',...(short?{}:{second:'2-digit'})}
+        : {dateStyle:short?'short':'full'});
+      const twelve = ['h11','h12'].includes(formatter.resolvedOptions().hourCycle);
+      return formatter.formatToParts(new Date(2024,10,23,17,45,36)).map(p => {
+        switch(p.type) {
+          case 'year': return p.value.length === 2 ? 'yy' : 'yyyy';
+          case 'month': return /^\d+$/.test(p.value) ? (p.value.length === 2 ? 'MM' : 'M') : 'MMMM';
+          case 'day': return p.value.length === 2 ? 'dd' : 'd';
+          case 'weekday': return 'dddd';
+          case 'hour': return twelve ? 'h' : 'HH';
+          case 'minute': return 'mm';
+          case 'second': return 'ss';
+          case 'dayPeriod': return 'AP';
+          default: return /[A-Za-z']/.test(p.value) ? "'"+p.value.replaceAll("'","''")+"'" : p.value;
+        }
+      }).join('');
+    };
+    return {name:actual.replaceAll('-','_'),measurementSystem:region==='US'?1:region==='GB'?2:0,
+      timeFormat:format=>pattern(true,format===1),dateFormat:format=>pattern(false,format===1)};
+  }
+  function formatDateTime(input,format='ddd MMM d yyyy HH:mm:ss') {
+    const d=input instanceof Date?input:new Date(input);if(!Number.isFinite(d.getTime()))return '';
+    const pad=(n,width=2)=>String(n).padStart(width,'0'),hour=/AP|ap/.test(format)?d.getHours()%12||12:d.getHours();
+    const localTag=systemLocale('LC_TIME'), intlTag=localTag==='C'?'en-US':localTag;
+    const names=(options)=>new Intl.DateTimeFormat(intlTag,options).format(d);
+    const values={yyyy:d.getFullYear(),yy:pad(d.getFullYear()%100),MMMM:names({month:'long'}),MMM:names({month:'short'}),MM:pad(d.getMonth()+1),M:d.getMonth()+1,dddd:names({weekday:'long'}),ddd:names({weekday:'short'}),dd:pad(d.getDate()),d:d.getDate(),HH:pad(d.getHours()),H:d.getHours(),hh:pad(hour),h:hour,mm:pad(d.getMinutes()),m:d.getMinutes(),ss:pad(d.getSeconds()),s:d.getSeconds(),zzz:pad(d.getMilliseconds(),3),z:d.getMilliseconds(),AP:d.getHours()<12?'AM':'PM',ap:d.getHours()<12?'am':'pm',t:new Intl.DateTimeFormat(undefined,{timeZoneName:'short'}).formatToParts(d).find(p=>p.type==='timeZoneName')?.value||''};
+    return String(format).replace(/'((?:[^']|'')*)'|yyyy|MMMM|dddd|zzz|MMM|ddd|yy|MM|dd|HH|hh|mm|ss|AP|ap|[MdHhmszt]/g,(token,literal)=>literal!==undefined?literal.replaceAll("''", "'"):String(values[token]));
+  }
   return {
+    locale,formatDateTime,formatTime:(date,format="HH:mm:ss")=>formatDateTime(date,format),formatDate:(date,format="ddd MMM d yyyy")=>formatDateTime(date,format),
+    NoFocus:0, TabFocus:1, ClickFocus:2, StrongFocus:3,
+    WindowShortcut: 1, ApplicationShortcut: 2,
     ...Object.fromEntries(
       Object.entries(keys).map(([name, value]) => ['Key_' + name, value]),
     ),
@@ -634,6 +702,9 @@ export function createQt() {
         y = color(b);
       return ['r', 'g', 'b', 'a'].every((k) => Math.abs(x[k] - y[k]) < 1 / 255);
     },
+    vector2d: (x,y)=>({x:Number(x),y:Number(y)}),
+    vector3d: (x,y,z)=>({x:Number(x),y:Number(y),z:Number(z)}),
+    vector4d: (x,y,z,w)=>({x:Number(x),y:Number(y),z:Number(z),w:Number(w)}),
     point: (x, y) => ({ x, y }),
     size: (width, height) => ({ width, height }),
     rect: (x, y, width, height) => ({ x, y, width, height }),