buninu-browser 0.3.0 → 0.5.0

package/LICENSES/jsmdcui.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2016-2020: Zachary Yedidia, et al.
+Copyright (c) 2026 Dr. John (醫者小智)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,17 @@ directly as JavaScript and WebAssembly.
 > [!WARNING]
 > Buninu Browser is in an early experimental stage and is not yet a
 > general-purpose browser engine or replacement for Chromium. The headless
-> shell is the initial frontend; native windowed frontends are planned later.
+> shell is the initial frontend; a standard Wayland frontend is experimental.
+
+## Experimental Wayland frontend
+
+`bun index.js --wayland URL` opens a standard Wayland SHM window using
+`WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR`. Casty remains the default.
+See [frontend details and limitations](frontends/wayland/README.md).
+See the [experimental QML runtime and Flea/Omastorm container recipes](lib/qml/README.md)
+for local QML applications. This does not yet provide full Quickshell/Flea/Omastorm
+compatibility. For input checks, open `test/manual-pointer-scroll.html` through
+either frontend.
 
 ## Usage
 
@@ -218,11 +228,19 @@ not start a browser process or CDP listener.
 
 ### Page sandbox
 
-Pages can copy text with `navigator.clipboard.writeText()` after a user click
-or key press on HTTPS (or localhost). The controller writes the clipboard,
+Pages can copy or read text with `navigator.clipboard.writeText()` and
+`navigator.clipboard.readText()` after a user click or key press on HTTPS
+(or localhost). Each operation consumes that activation. The controller accesses the clipboard,
 preferring `xclip -selection clipboard`, with platform clipboard commands as
 fallbacks. Clipboard command access stays outside the page sandbox; unavailable
-providers reject the promise instead of reporting a successful copy.
+providers reject the promise instead of reporting success. Reads happen only
+on request, with no clipboard polling. HTML inputs and textareas share selection,
+caret blinking, Shift+arrows, and Ctrl+C/X/V editing with QML controls. Paste
+replaces the selection, or inserts at the cursor. Up/Down currently follow
+explicit textarea line breaks, not soft-wrapped visual lines.
+
+PowerShell clipboard quoting and newline handling are reused from jsmdcui
+under its [MIT license](LICENSES/jsmdcui.txt).
 
 Page JavaScript runs behind three layers:
 
@@ -420,6 +438,24 @@ additional unreported downstream latency, such as Bluetooth output latency.
 With `BUNINU_LOG`, `media sync` records reported audio progress, the latest
 rendered video position, and the output queue/latency for diagnosis.
 
+### Render scheduling
+
+Set `BUNINU_RENDER_MIN_INTERVAL` to adjust the minimum delay before coalesced
+DOM/Canvas redraws. The default is 16 ms; try 8 ms for more frequent updates:
+
+```sh
+env BUNINU_RENDER_MIN_INTERVAL=8 bun index.js --wayland URL
+env BUNINU_RENDER_MIN_INTERVAL=8 bun index.js URL
+```
+
+Accepts integer milliseconds from 0 to 60000. Invalid values warn and fall back
+to 16 ms. Zero removes the minimum delay, but retains asynchronous coalescing
+and the adaptive delay based on the previous layout cost. This is not an FPS
+guarantee or Casty's capture interval; shorter waits can increase CPU usage.
+Restart the browser after changing it. The setting also applies to iframe
+renderers, and only its validated numeric value is forwarded to the renderer
+process; the ordinary renderer does not inherit the host environment.
+
 ### Diagnostics
 
 [`test/fixtures/browser-raw-demo.html`](test/fixtures/browser-raw-demo.html)

package/frontends/wayland/LICENSE-land

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. John (醫者小智)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/frontends/wayland/README.md

@@ -0,0 +1,152 @@
+# Experimental Wayland frontend / 實驗性 Wayland 前端
+
+```sh
+XDG_RUNTIME_DIR=/tmp WAYLAND_DISPLAY=wayland-buninu \
+  bun index.js --wayland file:///absolute/path/to/hello.qml
+# HTML works through the same frontend:
+bun index.js --wayland https://example.com --window-size=800,600
+```
+
+Uses the existing browser controller and renderer. No Qt, libwayland, native addon,
+new dependency, PNG encoding, or base64. Only libc is loaded, because Bun sockets
+cannot send/receive SCM_RIGHTS ancillary file descriptors. Linux/Android 64-bit only.
+The default launcher remains Casty. External integration blocks in index.js are
+marked `wayland handle`; the frontend lives entirely in this directory.
+
+沿用現有 Browser controller 與 renderer，不新增依賴；僅為傳送 fd 使用 libc。
+預設仍是 Casty，只有指定 `--wayland` 才啟用。入口整合標記為 `wayland handle`。
+
+## Address bar / 網址列
+
+Ordinary pages have a 32-pixel address bar. Click the URL or press Alt+L to edit;
+click `@` or press Ctrl+E for `cmd>`. Tab switches URL/command mode. Casty's editor
+provides horizontal scrolling, Shift-arrow and mouse-drag selection, double-click
+history/submit gestures, and Ctrl+C / Alt+C copying plus Ctrl+V insertion (replacing
+selected text). Escape cancels editing; `q` quits. `help` lists applicable commands;
+CDP and terminal transport commands are omitted. QML applications have no bar.
+
+一般網頁頂部有 32 像素高的網址列。點網址或按 Alt+L 編輯，點 `@` 或按 Ctrl+E
+進入 `cmd>`；Tab 切換模式。沿用 Casty 的水平捲動、Shift 方向鍵與滑鼠拖曳選取、
+雙擊歷史／送出操作，以及 Ctrl+C／Alt+C 複製、Ctrl+V 插入（有選取時取代選取）。
+Escape 取消編輯，`q` 退出；`help` 列出適用命令，不包含 CDP 與終端傳輸命令。
+QML 應用不顯示網址列。
+
+Editing the address bar never pauses page frame updates. Only chrome-only changes
+reuse the latest page frame. The cached bar is rasterized separately; raw BGRA
+page bytes go straight to SHM beside the bar, without PNG or full-page canvas
+composition. The bar's small RGBA raster is converted to BGRA; page channels are
+not converted. Presentation still writes a complete SHM buffer.
+
+編輯網址列不會暫停頁面更新。只有網址列本身改變時才沿用上一張頁面；網址列獨立
+繪製並快取，頁面的 raw BGRA 直接與它分段寫入 SHM，不經 PNG 或整頁 Canvas
+合成。只有網址列的小圖需要 RGBA 轉 BGRA；提交仍需寫入完整 SHM buffer。
+
+`casty/` vendors Casty's MIT-licensed editor and helpers (license included).
+The editor changes replace terminal cursor output with a no-op and terminal column
+lookup with an injectable width; its rendering is overridden by `urlbar.js`.
+Page find/console helpers are extracted from Casty's input module. Navigation,
+clipboard and drawing are adapted here to the existing browser controller.
+
+`casty/` 保留 Casty 的 MIT 授權編輯器與輔助程式；移除終端游標輸出，欄寬改為
+可指定，繪製由 `urlbar.js` 覆寫。搜尋／console 輔助函式取自 Casty input 模組。
+導航、剪貼板與繪製則由此處的薄接層呼叫現有 browser controller。
+
+## Pixels and lifetime / 像素與生命週期
+
+`xdg_wm_base` → `xdg_surface` → `xdg_toplevel`; acknowledge configure before commit.
+`wl_shm` XRGB8888 buffers contain BGRX bytes on supported little-endian platforms.
+The browser currently supplies BGRA; XRGB deliberately ignores alpha (opaque window).
+At most two buffers are outstanding. A buffer is reused only after `wl_buffer.release`;
+frame callbacks pace commits and dirty events coalesce. Resize uses fresh buffers.
+SHM files are mode 0600 and unlinked immediately after opening.
+
+Current copies: renderer → browser raw temporary file → JS read → shared buffer →
+compositor. This first frontend does not promise zero-copy or GPU acceleration.
+The producer's raw file is removed after consumption, including error paths.
+
+使用標準共享記憶體、configure/ack、frame callback 與 buffer release。最多兩個
+尚未釋放的 buffer；不會覆寫 compositor 正在使用的 buffer。視窗目前不透明。
+目前仍有 raw 暫存檔讀取與共享 buffer 寫入，尚非零拷貝或 GPU 路徑。
+
+## Input and scope / 輸入與範圍
+
+Pointer motion, left/right/middle clicks, double clicks, scrolling on both axes,
+basic XKB keymap symbols and modifiers. Right clicks dispatch `contextmenu`;
+non-primary clicks dispatch `auxclick` without left-click navigation or form actions.
+Press, movement and release are delivered separately; held-button state reaches
+mousemove/pointermove so HTML canvas and QML drag handlers can draw before release.
+Focus occurs on an uncancelled left press. Click/auxclick uses the common ancestor
+of the press and release targets; removing the press target prevents activation.
+The same page event handling is available through CDP/Casty. QML MouseArea and
+TapHandler receive accepted non-primary buttons. Middle click does not yet paste
+PRIMARY selection, and selecting text does not publish a PRIMARY clipboard.
+Keyboard input uses the controller's existing paired keydown/keyup operation.
+Not full XKB: no compose, IME, layout groups, repeat, or independently held keys.
+No client cursor, drag/drop, popup, layer-shell or fractional scaling yet.
+Text controls, navigator.clipboard and the address bar share the Wayland data-device
+clipboard. Host tools are a fallback when no Wayland selection is offered; successful
+nonempty host reads are published to Wayland so Land can retain its text cache.
+Clipboard API security/user-activation checks remain in effect.
+文字框、navigator.clipboard 與網址列共用 Wayland 剪貼簿；沒有 Wayland 選取來源時
+才讀主機工具，成功取得的非空文字也送回 Wayland，讓 Land 可以快取。
+網頁 API 原本的安全來源與使用者操作檢查仍保留。
+Connection and window are separate objects, but the launcher currently opens one
+browser document/window. QML `ShellRoot` can group logical objects, but multiple independent native windows
+are not implemented.
+
+支援滑鼠移動、左／右／中鍵、雙擊及雙軸捲動。按下、移動與放開分別即時傳遞，
+mousemove／pointermove 保留按住狀態，讓 Canvas 與 QML 可在放開前處理拖曳。
+未取消的左鍵按下會取得焦點；click／auxclick 以按下與放開元素的共同祖先為目標，
+按下元素已被移除時不觸發點擊。右鍵送出 contextmenu，非左鍵送出
+auxclick，不執行左鍵導航或表單動作；CDP／Casty 也共用這些事件。QML MouseArea
+與 TapHandler 可收到允許的非左鍵按鈕。選取文字尚不發布 PRIMARY，中鍵也不會
+自動貼上 PRIMARY。尚非完整 XKB/IME；按鍵沿用 controller 的成對
+按下／放開，不支援獨立長按。啟動器目前只有單一文件／視窗。
+
+## Compatibility targets / 相容性目標
+
+The official Flea binary can launch the experimental QML wrapper; directory
+navigation, previews and selected file operations have been exercised. Omastorm
+has a software ShaderEffect experiment and a reproducible container recipe.
+See [QML setup and limitations](../../lib/qml/README.md) for required backends,
+fonts, external tools and the explicit Omastorm software-path adaptation.
+Neither result implies complete Qt/Quickshell compatibility: independent native
+windows, tab tearoff/layer-shell and arbitrary shaders remain outside this scope.
+Ordinary web pages do not acquire the local QML host's file/process permissions.
+
+官方 Flea binary 已可啟動實驗性 QML wrapper，並測試目錄導航、預覽與部分檔案操作。
+Omastorm 已有軟體 ShaderEffect 實驗及容器教學；所需後端、字型、外部工具與
+Omastorm 的軟體路徑調整，見 [QML 說明](../../lib/qml/README.md)。這不代表完整
+Qt／Quickshell 相容；獨立原生多視窗、分離分頁／layer-shell、任意 shader 仍有限制。
+一般網頁不會因此取得本地 QML 的檔案或程序權限。
+
+References: https://github.com/thisisgm/flea and https://github.com/wesleygrimes/omastorm
+
+## Verification / 測試
+
+```sh
+bun test test/wayland-frontend.test.js test/double-click.test.js test/wayland-urlbar.test.js test/pointer-drag.test.js
+# Optional integration with the existing sibling buninu-land checkout:
+BUNINU_TEST_WAYLAND=1 bun test test/wayland-frontend.test.js test/wayland-scroll.test.js test/pointer-drag.test.js
+# Optional reference comparison with /usr/local/bin/chromium-headless-shell:
+BUNINU_TEST_CHROMIUM=1 bun test test/pointer-drag.test.js
+```
+
+The integration test creates its own compositor/socket; it does not interrupt the
+user's compositor. Checks SHM presentation, pointer click, keyboard and resize.
+整合測試使用獨立 socket，不影響使用者正在執行的 Land。
+
+Protocol XML retains upstream license notices. Transport/protocol code adapted
+from Buninu Land (MIT), see LICENSE-land. XML is interpreted at runtime with Bun.XML.
+
+Manual mouse/scroll test / 手動滑鼠與捲動測試：
+
+```sh
+bun index.js --wayland file://"$PWD"/test/manual-pointer-scroll.html
+# Omit --wayland to use the default Casty frontend.
+```
+
+The page includes vertical/horizontal/two-axis scroll boxes, button and double-click
+counters, a drag canvas, text controls and bounded event logs. It reports received
+modifiers without swapping wheel axes itself. 頁面不自行轉換滾輪方向，可從紀錄
+確認外層是否真的送來水平軸與修飾鍵；預設 Casty 路徑可省略 `--wayland`。

package/frontends/wayland/casty/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hironobu Sano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/frontends/wayland/casty/bookmarks.js

@@ -0,0 +1,32 @@
+// Bookmarks
+// Reads ~/.casty/bookmarks.json, searchable via /b in the address bar
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadJsonFile } from './config.js';
+
+const bookmarkPath = join(homedir(), '.casty', 'bookmarks.json');
+
+// Load bookmarks (normalized to [{ name, url }, ...])
+export function loadBookmarks() {
+  const data = loadJsonFile(bookmarkPath, []);
+  // { "name": "url", ... } object format
+  if (!Array.isArray(data) && typeof data === 'object') {
+    return Object.entries(data).map(([name, url]) => ({ name, url }));
+  }
+  // [{ name, url }, ...] array format
+  if (Array.isArray(data)) {
+    return data.filter(e => e.name && e.url);
+  }
+  return [];
+}
+
+// Search bookmarks by query (case-insensitive partial match on name/URL)
+export function searchBookmarks(query) {
+  const bookmarks = loadBookmarks();
+  if (!query) return bookmarks;
+  const q = query.toLowerCase();
+  return bookmarks.filter(b =>
+    b.name.toLowerCase().includes(q) || b.url.toLowerCase().includes(q)
+  );
+}

package/frontends/wayland/casty/click.js

@@ -0,0 +1,96 @@
+// Shared trusted-click synthesis for Chrome DevTools Protocol.
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// CASTY_DEBUG_CLICK=1 logs each click to ~/.casty/click.log
+const DEBUG_CLICK = !!process.env.CASTY_DEBUG_CLICK;
+const DEBUG_LOG = join(homedir(), '.casty', 'click.log');
+
+const DESCRIBE = `const d = el => !el ? null : el.tagName.toLowerCase()
+  + (el.id ? '#' + el.id : '')
+  + (typeof el.className === 'string' && el.className.trim() ? '.' + el.className.trim().split(/\\s+/).slice(0, 2).join('.') : '')
+  + ' "' + (el.innerText || el.value || '').trim().slice(0, 30).replace(/\\s+/g, ' ') + '"';`;
+
+// Input coordinates are in the visual viewport; the page's are layout
+// coordinates, which differ when the page is zoomed.
+const TO_LAYOUT = `const toLayout = (x, y) => {
+    const v = window.visualViewport, s = v?.scale || 1;
+    return [x / s + (v?.offsetLeft || 0), y / s + (v?.offsetTop || 0)];
+  };`;
+
+async function debugBefore(client, x, y) {
+  const expression = `(() => { ${DESCRIBE}
+    window.__castyClickLog = null;
+    document.addEventListener('click', e => {
+      window.__castyClickLog = { target: d(e.target), clientX: e.clientX, clientY: e.clientY };
+    }, { capture: true, once: true });
+    ${TO_LAYOUT}
+    return { atPoint: d(document.elementFromPoint(...toLayout(${x}, ${y}))), vw: innerWidth, vh: innerHeight, dpr: devicePixelRatio, sx: scrollX, sy: scrollY };
+  })()`;
+  const { result } = await client.send('Runtime.evaluate', { expression, returnByValue: true });
+  return result?.value;
+}
+
+async function debugAfter(client) {
+  const { result } = await client.send('Runtime.evaluate', {
+    expression: 'window.__castyClickLog', returnByValue: true,
+  });
+  return result?.value ?? null;
+}
+
+export async function showClickMarker(client, x, y, duration = 800) {
+  const expression = `(async () => {
+    ${TO_LAYOUT}
+    const [left, top] = toLayout(${x}, ${y});
+    const old = document.getElementById('__casty_click_marker');
+    if (old) old.remove();
+    const marker = document.createElement('div');
+    marker.id = '__casty_click_marker';
+    marker.style.cssText = [
+      'position:fixed',
+      'left:' + left + 'px',
+      'top:' + top + 'px',
+      'width:14px',
+      'height:14px',
+      'margin-left:-7px',
+      'margin-top:-7px',
+      'box-sizing:border-box',
+      'border:2px solid white',
+      'border-radius:50%',
+      'background:#f00',
+      'box-shadow:0 0 0 2px rgba(255,0,0,.45)',
+      'pointer-events:none',
+      'z-index:2147483647',
+    ].join(';');
+    document.documentElement.appendChild(marker);
+    setTimeout(() => marker.remove(), ${duration});
+    await new Promise(resolve => requestAnimationFrame(resolve));
+  })()`;
+  await client.send('Runtime.evaluate', { expression, awaitPromise: true });
+}
+
+export async function dispatchClick(client, x, y, { clickCount = 1, button = 'left', source = '?' } = {}) {
+  const before = DEBUG_CLICK ? await debugBefore(client, x, y).catch(e => ({ error: e.message })) : null;
+  // The marker is cosmetic. CDP engines without a page DOM (e.g. a Wayland
+  // compositor) can reject this evaluation but still support real input.
+  try { await showClickMarker(client, x, y); } catch {}
+  // Input coordinates are CSS pixels (see startBrowser for why they stay so)
+  const common = { x, y, button, clickCount };
+  await client.send('Input.dispatchMouseEvent', {
+    type: 'mousePressed', ...common, buttons: button === 'right' ? 2 : 1,
+  });
+  await client.send('Input.dispatchMouseEvent', {
+    type: 'mouseReleased', ...common, buttons: 0,
+  });
+  if (DEBUG_CLICK) {
+    const after = await debugAfter(client).catch(e => ({ error: e.message }));
+    const line = JSON.stringify({
+      t: new Date().toISOString(), source, button, css: [x, y], clickCount, before, clicked: after,
+    });
+    try {
+      mkdirSync(join(homedir(), '.casty'), { recursive: true });
+      appendFileSync(DEBUG_LOG, line + '\n');
+    } catch {}
+  }
+}

package/frontends/wayland/casty/commands.js

@@ -0,0 +1,61 @@
+// Command line: Ctrl+E turns the address bar into a "cmd> " prompt.
+// Each command maps to an action in input.js; `help` lists them.
+
+export const COMMANDS = [
+  { name: 'open', aliases: ['o', 'go'], usage: 'open <url|query>', help: 'Open a URL or search' },
+  { name: 'back', aliases: ['b'], usage: 'back', help: 'Go back' },
+  { name: 'forward', aliases: ['f'], usage: 'forward', help: 'Go forward' },
+  { name: 'reload', aliases: ['r'], usage: 'reload', help: 'Reload the page' },
+  { name: 'home', aliases: [], usage: 'home', help: 'Open the home page' },
+  { name: 'bookmark', aliases: ['bm'], usage: 'bookmark [query]', help: 'Open the first matching bookmark' },
+  { name: 'links', aliases: ['hints', 'l'], usage: 'links', help: 'Hint mode: pick a link to click' },
+  { name: 'copy', aliases: ['c'], usage: 'copy', help: 'Copy the selected text' },
+  { name: 'copyurl', aliases: ['yank', 'y'], usage: 'copyurl', help: 'Copy the page URL' },
+  { name: 'paste', aliases: ['p'], usage: 'paste', help: 'Paste the clipboard into the page' },
+  { name: 'pasteurl', aliases: ['pu'], usage: 'pasteurl', help: 'Put the clipboard into the address bar to edit or send' },
+  { name: 'download', aliases: ['dl', 'save'], usage: 'download', help: 'Save the page as the browser received it to the Downloads folder' },
+  { name: 'find', aliases: ['/'], usage: 'find [text] (or /text)', help: 'Find text in the page; again for the next match' },
+  { name: 'eruda', aliases: ['devtools'], usage: 'eruda', help: 'Show or hide the eruda console in the page (loaded from a CDN)' },
+  { name: 'zoom', aliases: ['z'], usage: 'zoom [n|n%|+|-|reset]', help: 'Show or set the zoom (1 = automatic)' },
+  { name: 'cdp', aliases: [], usage: 'cdp [ws]', help: 'Show CDP address, state and engine; ws shows the full WebSocket URL' },
+  { name: 'kitty', aliases: [], usage: 'kitty [inline|file]', help: 'Show image transport and capture format, or switch transport' },
+  { name: 'pixelmouse', aliases: [], usage: 'pixelmouse [on|off]', help: 'Query and enable pixel mouse, or use cell coordinates' },
+  { name: 'help', aliases: ['?', 'h'], usage: 'help', help: 'List commands' },
+  { name: 'quit', aliases: ['q', 'exit'], usage: 'quit', help: 'Quit casty' },
+];
+
+const BY_NAME = new Map(COMMANDS.flatMap(c => [[c.name, c], ...c.aliases.map(a => [a, c])]));
+
+// "zoom 1.5" → { name: 'zoom', arg: '1.5' }; "/text" finds; unknown → { error }
+export function parseCommand(line) {
+  const text = line.trim();
+  if (text.startsWith('/')) return { name: 'find', arg: text.slice(1).trim() };
+  const m = text.match(/^(\S+)\s*(.*)$/);
+  if (!m) return { error: 'Empty command' };
+  const command = BY_NAME.get(m[1].toLowerCase());
+  if (!command) return { error: `Unknown command: ${m[1]} (try help)` };
+  return { name: command.name, arg: m[2] };
+}
+
+// One-line command summary for the status bar
+export function helpText() {
+  return COMMANDS.map(c => c.usage).join(' · ');
+}
+
+// Browser-style zoom steps for "zoom +" / "zoom -"
+const ZOOM_STEPS = [0.25, 0.33, 0.5, 0.67, 0.75, 0.8, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2, 2.5, 3, 4, 5];
+export const MIN_ZOOM = ZOOM_STEPS[0];
+export const MAX_ZOOM = ZOOM_STEPS.at(-1);
+
+// New zoom factor for a "zoom" argument, or null if it is not one.
+// "1.5" and "150%" are absolute; "+"/"-" step; "reset" (or "0") goes back to 1.
+export function parseZoom(arg, current = 1) {
+  const text = arg.trim().toLowerCase();
+  if (text === 'reset' || text === '0') return 1;
+  if (text === '+' || text === 'in') return ZOOM_STEPS.find(s => s > current + 1e-9) ?? MAX_ZOOM;
+  if (text === '-' || text === 'out') return ZOOM_STEPS.findLast(s => s < current - 1e-9) ?? MIN_ZOOM;
+  const m = text.match(/^(\d+(?:\.\d+)?|\.\d+)(%?)$/);
+  if (!m) return null;
+  const value = Number(m[1]) / (m[2] ? 100 : 1);
+  return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, value));
+}

package/frontends/wayland/casty/config.js

@@ -0,0 +1,45 @@
+// Configuration
+// Customizable via ~/.casty/config.json (falls back to defaults)
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Safely load and parse a JSON file (returns fallback on parse error or missing file)
+export function loadJsonFile(filePath, fallback) {
+  try { return JSON.parse(readFileSync(filePath, 'utf8')); }
+  catch { return fallback; }
+}
+
+const configPath = join(homedir(), '.casty', 'config.json');
+
+// Detect system locale (e.g. "en-US", "ja", "zh-CN")
+function detectLocale() {
+  // Environment variables first (Intl may lack ICU data and return en-US)
+  const env = process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || '';
+  const m = env.match(/^([a-z]{2})(?:[_-]([A-Z]{2}))?/);
+  if (m) return m[2] ? `${m[1]}-${m[2]}` : m[1];
+  // Fallback to Intl API
+  try {
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (locale) return locale;
+  } catch {}
+  return 'en-US';
+}
+
+const DEFAULTS = {
+  homeUrl: 'https://github.com/jjtseng93/casty',
+  searchUrl: 'https://www.google.com/search?q=',
+  transport: 'auto', // 'auto' | 'file' | 'inline'
+  format: 'auto',    // 'auto' | 'png' | 'jpeg'
+  media: false,      // Enable camera/mic via ffmpeg for WebRTC (requires ffmpeg)
+  language: detectLocale(), // System locale (override: "en-US", "ja", etc.)
+};
+
+let _cache = null;
+
+export function loadConfig() {
+  if (_cache) return _cache;
+  _cache = { ...DEFAULTS, ...loadJsonFile(configPath, {}) };
+  return _cache;
+}

package/frontends/wayland/casty/download-directory.js

@@ -0,0 +1,28 @@
+import { homedir } from 'node:os';
+import { join, win32 } from 'node:path';
+
+// Windows can move the Downloads known folder away from %USERPROFILE%. Query
+// its registered location through PowerShell so non-ASCII paths stay UTF-8.
+const WINDOWS_DOWNLOADS = [
+  '$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)',
+  "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders')",
+  "if ($key) { $path = $key.GetValue('{374DE290-123F-4565-9164-39C4925E467B}'); if ($path) { [Console]::Write([Environment]::ExpandEnvironmentVariables($path)) } }",
+].join('; ');
+
+function windowsDownloads() {
+  try {
+    const result = Bun.spawnSync({ cmd: ['powershell.exe', '-NoProfile', '-NonInteractive', '-Command', WINDOWS_DOWNLOADS],
+      stdout: 'pipe', stderr: 'ignore' });
+    return result.exitCode === 0 ? new TextDecoder().decode(result.stdout).trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function downloadsDirectory({ platform = process.platform, home = homedir(), queryWindows = windowsDownloads } = {}) {
+  if (platform === 'win32') {
+    const known = queryWindows();
+    return known && win32.isAbsolute(known) ? known : win32.join(home, 'Downloads');
+  }
+  return join(home, 'Downloads');
+}

package/frontends/wayland/casty/download.js

@@ -0,0 +1,49 @@
+// "download" (Ctrl+E): save the current page's document as the browser
+// received it, via CDP Page.getResourceContent (Chrome and buninu-browser),
+// into the same folder as browser downloads.
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { downloadsDirectory } from './download-directory.js';
+
+export const DOWNLOAD_DIR = downloadsDirectory();
+
+// A file name for a URL: its last path segment, else its host; characters
+// Windows and POSIX reject become "_", and an HTML page without an extension
+// gets ".html".
+export function fileNameFor(url, mimeType = '') {
+  let name = '';
+  let host = 'page';
+  try {
+    const parsed = new URL(url);
+    host = parsed.hostname || host;
+    const segment = parsed.pathname.split('/').filter(Boolean).pop() ?? '';
+    try { name = decodeURIComponent(segment); } catch { name = segment; }
+  } catch {}
+  // A host name ("example.com") has no file extension of its own.
+  const fromHost = !name;
+  name = (name || host).replace(/[\\/:*?"<>|\x00-\x1f]/g, '_').replace(/^\.+/, '_').slice(0, 200);
+  if ((fromHost || !extname(name)) && /html/i.test(mimeType)) name += '.html';
+  return name;
+}
+
+// dir/name, or dir/name (2).ext, (3)… when it exists.
+export function uniquePath(dir, name, exists = existsSync) {
+  const extension = extname(name);
+  const base = name.slice(0, name.length - extension.length);
+  let candidate = join(dir, name);
+  for (let n = 2; exists(candidate); n++) candidate = join(dir, `${base} (${n})${extension}`);
+  return candidate;
+}
+
+// Saves the main frame's document; returns the path written.
+export async function downloadPage(client, dir = DOWNLOAD_DIR) {
+  const { frameTree } = await client.send('Page.getFrameTree');
+  const { id: frameId, url, mimeType } = frameTree.frame;
+  if (!/^(https?|file|data):/.test(url)) throw new Error(`Nothing to download for ${url}`);
+  const { content, base64Encoded } = await client.send('Page.getResourceContent', { frameId, url });
+  mkdirSync(dir, { recursive: true });
+  const path = uniquePath(dir, fileNameFor(url, mimeType));
+  writeFileSync(path, base64Encoded ? Buffer.from(content, 'base64') : Buffer.from(content, 'utf8'));
+  return path;
+}