buninu-browser 0.3.0 → 0.5.0

package/test/fixtures/title-no-paint.js

@@ -0,0 +1,20 @@
+import {strict as assert} from 'node:assert';
+import {createPageRenderer} from '../../lib/renderer/page-renderer.js';
+const traces=[];
+const r=await createPageRenderer({trace:s=>traces.push(s)});
+try{
+ r.setScripting('host');
+ await r.loadDocument({url:'https://title.test/',contentType:'text/html',source:`<title>Initial</title><p>Before</p><script>globalThis.changeTitle=value=>{document.title=value;document.querySelector('p').textContent='Changed '+value};</script>`});
+ await r.whenLoaded();
+ assert.equal(r.title(),'Initial');
+ // Host scripting allows the fixture to mutate the DOM without evaluate()'s
+ // explicit refresh. No onFrame callback: pending work stays pending.
+ for(const title of ['Updated','']){
+  globalThis.changeTitle(title);
+  traces.length=0;
+  assert.equal(r.title(),title);
+  assert.equal(traces.length,0,'title reads must not rebuild or rasterize');
+  await r.screenshot();
+  assert.ok(traces.some(s=>s.includes('restyle and relayout')),'DOM mutations remain pending until rendering is requested');
+ }
+}finally{delete globalThis.changeTitle;r.dispose()}

package/test/helpers/flea-sandbox.js

@@ -0,0 +1,48 @@
+import { mkdtempSync, mkdirSync, symlinkSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// Application tests own every XDG directory. Backend replies are never replaced.
+export function fleaSandbox(flea, omarchy) {
+  const dir = mkdtempSync('/tmp/qml-flea-'),
+    saved = {};
+  const values = {
+    HOME: join(dir, 'home'),
+    XDG_CONFIG_HOME: join(dir, 'config'),
+    XDG_STATE_HOME: join(dir, 'state'),
+    XDG_DATA_HOME: join(dir, 'data'),
+    XDG_CACHE_HOME: join(dir, 'cache'),
+    QML_IMPORT_PATH: join(dir, 'imports'),
+    HYPRLAND_INSTANCE_SIGNATURE: '',
+    FLEA_BIN: process.env.FLEA_BIN || join(dir, 'no-flea-backend'),
+  };
+  for (const [key, value] of Object.entries(values)) {
+    saved[key] = process.env[key];
+    process.env[key] = value;
+  }
+  for (const key of [
+    'HOME',
+    'XDG_CONFIG_HOME',
+    'XDG_STATE_HOME',
+    'XDG_DATA_HOME',
+    'XDG_CACHE_HOME',
+  ])
+    mkdirSync(values[key], { recursive: true });
+  mkdirSync(join(dir, 'imports/qs'), { recursive: true });
+  for (const name of ['Commons', 'Ui'])
+    symlinkSync(
+      resolve(omarchy, 'shell', name),
+      join(dir, 'imports/qs', name),
+      'dir',
+    );
+  return {
+    dir,
+    flea: resolve(flea),
+    values,
+    close() {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}

package/test/helpers/quickshell-fixture.js

@@ -0,0 +1,125 @@
+import {
+  mkdtempSync,
+  cpSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+} from 'node:fs';
+import { join } from 'node:path';
+export async function withQuickshellFixture(file, callback) {
+  const { start } = await import('../../../buninu-land/compositor.js');
+  const qsRoot = process.env.BUNINU_QS_ROOT,
+    dir = mkdtempSync('/tmp/qs-qml-test-'),
+    fixture = join(dir, 'fixture'),
+    home = join(dir, 'home'),
+    oldRuntime = process.env.XDG_RUNTIME_DIR;
+  let land, child;
+  try {
+    cpSync(
+      Bun.fileURLToPath(
+        new URL('../fixtures/qml/flea-theme/', import.meta.url),
+      ),
+      fixture,
+      { recursive: true },
+    );
+    const trim = (path) => {
+      for (const e of readdirSync(path, { withFileTypes: true })) {
+        const p = join(path, e.name);
+        if (e.isDirectory()) trim(p);
+        else if (e.name === 'qmldir')
+          writeFileSync(
+            p,
+            readFileSync(p, 'utf8')
+              .split('\n')
+              .filter((line) => {
+                const last = line.trim().split(/\s+/).at(-1);
+                return !last.endsWith('.qml') || existsSync(join(path, last));
+              })
+              .join('\n'),
+          );
+      }
+    };
+    trim(fixture);
+    const theme = join(home, '.local/state/omarchy/current/theme');
+    mkdirSync(theme, { recursive: true });
+    writeFileSync(join(theme, 'shell.toml'), '[font]\nbase-size = 14\n');
+    writeFileSync(
+      join(theme, 'colors.toml'),
+      'background="#101315"\nforeground="#eeeeee"\naccent="#70e1e8"\n',
+    );
+    writeFileSync(join(theme, '../theme.name'), 'demo');
+    process.env.XDG_RUNTIME_DIR = dir;
+    land = await start(['--remote-debugging-port=0', '--window-size=900,700']);
+    const lib = join(qsRoot, 'usr/lib/aarch64-linux-gnu');
+    child = Bun.spawn(
+      [
+        join(lib, 'ld-linux-aarch64.so.1'),
+        '--library-path',
+        lib + ':' + join(qsRoot, 'usr/lib'),
+        join(qsRoot, 'usr/bin/qs'),
+        '-p',
+        join(fixture, file),
+      ],
+      {
+        env: {
+          ...process.env,
+          HOME: home,
+          HYPRLAND_INSTANCE_SIGNATURE: '',
+          WAYLAND_DISPLAY: 'wayland-buninu',
+          QT_PLUGIN_PATH: join(lib, 'qt6/plugins'),
+          QML_IMPORT_PATH:
+            join(fixture, 'imports') + ':' + join(lib, 'qt6/qml'),
+          QT_QPA_PLATFORM: 'wayland',
+          QT_WAYLAND_DISABLE_WINDOWDECORATION: '1',
+          QT_QUICK_BACKEND: 'software',
+        },
+        stdout: 'ignore',
+        stderr: 'pipe',
+      },
+    );
+    const logs = new Response(child.stderr).text(),
+      title = () => land.compositor.wm.visible[0]?.surface.xdg.toplevel.title;
+    const until = async (fn) => {
+      for (let i = 0; i < 300; i++) {
+        if (await fn()) return;
+        if (child.exitCode !== null) throw Error(await logs);
+        await Bun.sleep(30);
+      }
+      throw Error('Quickshell state timed out: ' + title());
+    };
+    await until(() => title());
+    const mouse = async (type, x, y) => {
+      const surface = land.compositor.wm.renderSurfaces().find((s) => s.pixels);
+      const o = land.compositor.wm.origin(surface);
+      land.context.dispatchMouseEvent({
+        type,
+        x: o.x + x,
+        y: o.y + y,
+        button: 'left',
+      });
+      await Bun.sleep(40);
+    };
+    const click = async (x, y) => {
+      for (const type of ['mouseMoved', 'mousePressed', 'mouseReleased'])
+        await mouse(type, x, y);
+    };
+    const key = async (key, code, modifiers = 0) => {
+      for (const type of ['keyDown', 'keyUp'])
+        land.context.dispatchKeyEvent({ type, key, code, modifiers });
+      await Bun.sleep(80);
+    };
+    await callback({ land, title, until, mouse, click, key });
+  } finally {
+    if (child) {
+      child.kill();
+      await child.exited;
+    }
+    land?.close();
+    if (oldRuntime === undefined) delete process.env.XDG_RUNTIME_DIR;
+    else process.env.XDG_RUNTIME_DIR = oldRuntime;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/test/html-clipboard-wayland.test.js

@@ -0,0 +1,47 @@
+import {test,expect} from 'bun:test';
+import {mkdtempSync,rmSync} from 'node:fs';
+import {launch} from '../frontends/wayland/index.js';
+test.skipIf(process.env.BUNINU_TEST_WAYLAND!=='1')('HTML Ctrl-C/V, navigator and toolbar share Land clipboard even with host denied',async()=>{
+ const {start}=await import('../../buninu-land/compositor.js');
+ const dir=mkdtempSync('/tmp/html-clipboard-'),old=process.env.XDG_RUNTIME_DIR;
+ let land,app;const copied='Wayland 中文',writes=[];
+ const wait=async fn=>{for(let i=0;i<200;i++){if(await fn())return;await Bun.sleep(20);}throw Error('Clipboard did not settle');};
+ const server=Bun.serve({hostname:'127.0.0.1',port:0,fetch:()=>new Response(`<input id="field" value="Wayland 中文"><button id="read" style="position:absolute;top:50px;left:0;width:100px;height:30px" onclick="navigator.clipboard.readText().then(t=>globalThis.readResult=t)">Read</button>`,{headers:{'content-type':'text/html; charset=utf-8'}})});
+ const url=`http://127.0.0.1:${server.port}/`;
+ const run=s=>app.browser.context.evaluate(s);
+ const key=async(key,modifiers=2)=>{
+  for(const type of ['keyDown','keyUp'])land.context.dispatchKeyEvent({type,key,code:'Key'+key.toUpperCase(),modifiers});
+  await Bun.sleep(100);
+ };
+ try{
+  process.env.XDG_RUNTIME_DIR=dir;
+  land=await start(['--remote-debugging-port=0','--window-size=640,480']);
+  land.compositor.clipboard.host={write:async text=>{writes.push(text);throw Error('Android background denied');},read:async()=>{throw Error('Android background denied');},close(){}};
+  app=await launch({url,socket:dir+'/wayland-buninu'});
+  await wait(()=>app.client.clipboard.serial>0);
+  await run('document.getElementById("field").focus();document.getElementById("field").select()');
+  await key('c');await wait(()=>writes.length>0);expect(writes.at(-1)).toBe(copied);
+  await key('ArrowRight',0);await key('v');
+  await wait(async()=>await run('document.getElementById("field").value')===copied+copied);
+  app.close();await app.done;
+  await wait(()=>land.compositor.clipboard.selection?.cachedText);
+  app=await launch({url,socket:dir+'/wayland-buninu'});
+  await wait(()=>app.client.clipboard.selection>0);
+  await run('document.getElementById("field").focus();document.getElementById("field").select()');
+  await key('Backspace',0);await key('v');
+  await wait(async()=>await run('document.getElementById("field").value')===copied);
+  await app.browser.context.click(20,65);
+  await wait(async()=>await run('globalThis.readResult')===copied);
+  // URL bar uses the same selection and the same denied-host fallback.
+  app.toolbar.open(true);await key('v');await wait(()=>app.toolbar.editor.text===copied);
+  expect(land.compositor.clipboard.textCache.bytes.toString()).toBe(copied);
+  // Copy a partial URL-bar selection through the compositor, then insert it.
+  await key('ArrowRight',0);await key('ArrowLeft',8);await key('c');
+  await wait(()=>writes.at(-1)==='文');
+  await key('ArrowRight',0);await key('v');
+  await wait(()=>app.toolbar.editor.text===copied+'文');
+  // Pasting over a selection replaces it rather than appending twice.
+  await key('ArrowLeft',8);await key('v');
+  await wait(()=>app.toolbar.editor.text===copied+'文');
+ }finally{app?.close();land?.close();server.stop(true);if(old===undefined)delete process.env.XDG_RUNTIME_DIR;else process.env.XDG_RUNTIME_DIR=old;rmSync(dir,{recursive:true,force:true});}
+},30000);

package/test/index.test.js

@@ -27,3 +27,16 @@ test("casty runs with npx when npx and bun exist, else bunx, else bun x", () =>
   expect(castyCommand(["a"], (name) => name === "bun" ? "/bin/bun" : null)).toEqual(["/bin/bun", "x", ...casty, "a"]);
   expect(castyCommand([], () => null)).toEqual([process.argv0, "x", ...casty]);
 });
+
+test("explicit Quickshell backends and their help work through the package entry", async () => {
+  for (const backend of ["wayland", "headless", "casty"]) {
+    const flag = `--quickshell-${backend}`;
+    expect(chooseFrontend([flag, "-p", "shell.qml", "--", "--help"]))
+      .toEqual({ frontend: flag.slice(2), args: ["-p", "shell.qml", "--", "--help"] });
+    const child = Bun.spawn([process.execPath, new URL('../index.js', import.meta.url).pathname, flag, '--help'], { stdout: 'pipe', stderr: 'pipe' });
+    const output = await new Response(child.stdout).text();
+    expect(await child.exited).toBe(0);
+    expect(output).toContain(flag);
+    expect(output).toContain('-p, --path');
+  }
+});

package/test/manual-casty-without-qml.js

@@ -0,0 +1,87 @@
+// bun test/manual-casty-without-qml.js /path/to/stripped/buninu-browser
+// Actual Casty PTY -> CDP -> browser. An isolated xclip/OSC52 store avoids touching
+// the user's clipboard. A minimal Kitty peer acknowledges file/raw support.
+import assert from 'node:assert/strict';
+import {mkdtempSync,mkdirSync,writeFileSync,readFileSync,existsSync,unlinkSync} from 'node:fs';
+import {join,resolve} from 'node:path';
+const root=resolve(Bun.argv[2]||join(import.meta.dir,'..'));
+const casty=resolve(import.meta.dir,'../../casty/index.js');
+const dir=mkdtempSync('/tmp/casty-without-qml-');
+const clip=join(dir,'clipboard'),endpointFile=join(dir,'cdp');
+mkdirSync(join(dir,'bin'));mkdirSync(join(dir,'.casty'));
+writeFileSync(join(dir,'.casty/config.json'),JSON.stringify({transport:'auto',format:'auto',media:false}));
+writeFileSync(clip,'initial');
+writeFileSync(join(dir,'bin/xclip'),`#!${process.execPath}\nconst p=process.env.TEST_CLIPBOARD_FILE;if(Bun.argv.includes('-o'))process.stdout.write(await Bun.file(p).text());else await Bun.write(p,await Bun.stdin.text());\n`,{mode:0o755});
+writeFileSync(join(dir,'browser.js'),`import {writeFileSync} from 'node:fs';
+const report=(text)=>{const start=String(text).indexOf('ws://');if(String(text).includes('DevTools listening on ')&&start>=0)writeFileSync(${JSON.stringify(endpointFile)},String(text).slice(start).trim())};
+const error=console.error;console.error=(...args)=>{report(args.join(' '));error(...args)};
+const write=process.stderr.write.bind(process.stderr);process.stderr.write=(text,...args)=>{report(text);return write(text,...args)};
+const {main}=await import(${JSON.stringify(Bun.pathToFileURL(join(root,'buninu-browser.js')).href)});await main();`);
+const html=`<!doctype html><meta charset="utf-8"><title>Casty editing probe</title><style>body{margin:16px;background:#eef4f7;font:18px sans-serif}input,textarea{display:block;width:400px;margin:12px 0;font:20px monospace}textarea{height:100px}button{height:44px;min-width:140px}</style><h1>Casty 中文</h1><input id="field" value="abc中文xyz"><textarea id="multi">abcd\nxy\n12345</textarea><button id="write">API copy</button><button id="read">API paste</button><canvas id="canvas" width="200" height="60"></canvas><script>const c=document.getElementById('canvas').getContext('2d');c.fillStyle='#16a6a0';c.fillRect(0,0,200,60);document.getElementById('write').onclick=async()=>{try{await navigator.clipboard.writeText('navigator 中文');globalThis.writeStatus='ok'}catch(e){globalThis.writeStatus=e.name}};document.getElementById('read').onclick=async()=>{try{globalThis.readResult=await navigator.clipboard.readText()}catch(e){globalThis.readResult=e.name}};</script>`;
+const server=Bun.serve({hostname:'127.0.0.1',port:0,fetch:()=>new Response(html,{headers:{'content-type':'text/html; charset=utf-8'}})});
+let proc,ws,terminalTail='',output='',frames=0,rawFrames=0,lastRaw,oscReads=0;
+const wait=async(fn,label)=>{for(let i=0;i<400;i++){if(await fn())return;await Bun.sleep(25);}throw Error('Timed out: '+label+'\n'+output.slice(-1500))};
+const replies=(t,data)=>{
+ const s=Buffer.from(data).toString();output=(output+s).slice(-16000);terminalTail+=s;
+ const re=/\x1b_G([\s\S]*?)\x1b\\|\x1b\]52;[^;]*;([^\x07]*)(?:\x07)|\x1b\[14t|\x1b\[\?u/g;let m,last=0;
+ while((m=re.exec(terminalTail))){last=re.lastIndex;
+  if(m[1]!==undefined){
+   const [header,payload='']=m[1].split(';');const fields=Object.fromEntries(header.split(',').map(v=>v.split('=')));
+   if(fields.a==='q')t.write(`\x1b_Gi=${fields.i};${fields.f==='1111970369'?'OK Buninu1 bgra':'OK'}\x1b\\`);
+   if(fields.a==='T'){
+    frames++;
+    if(fields.f==='1111970369'&&['f','t'].includes(fields.t)){
+     const path=Buffer.from(payload,'base64').toString();
+     try{lastRaw=readFileSync(path);assert.equal(lastRaw.length,Number(fields.s)*Number(fields.v)*4);rawFrames++;if(fields.t==='t')unlinkSync(path);}catch(e){output+='\nframe error '+e;}
+    }
+   }
+  }else if(m[2]!==undefined){
+   if(m[2]==='?'){oscReads++;t.write('\x1b]52;c;'+readFileSync(clip).toString('base64')+'\x07');}
+   else writeFileSync(clip,Buffer.from(m[2],'base64'));
+  }else if(m[0]==='\x1b[14t')t.write('\x1b[4;640;640t');
+  else if(m[0]==='\x1b[?u')t.write('\x1b[?0u');
+ }
+ if(last)terminalTail=terminalTail.slice(last);if(terminalTail.length>100000)terminalTail=terminalTail.slice(-10000);
+};
+try{
+ proc=Bun.spawn([process.execPath,casty,`http://127.0.0.1:${server.port}/`],{env:{...process.env,HOME:dir,PATH:join(dir,'bin')+':'+process.env.PATH,CASTY_BROWSER:join(dir,'browser.js'),TEST_CLIPBOARD_FILE:clip,TERM:'xterm-256color',TMUX:''},terminal:{cols:80,rows:32,data:replies}});
+ await wait(()=>existsSync(endpointFile),'CDP startup');
+ const endpoint=new URL(readFileSync(endpointFile,'utf8'));
+ let pages;await wait(async()=>{pages=await fetch('http://'+endpoint.host+'/json/list').then(r=>r.json());return pages.length>0},'Casty page target');
+ ws=new WebSocket(pages[0].webSocketDebuggerUrl);await new Promise((yes,no)=>{ws.onopen=yes;ws.onerror=no});
+ let id=0;const requests=new Map();ws.onmessage=e=>{const m=JSON.parse(e.data);const p=requests.get(m.id);if(p){requests.delete(m.id);m.error?p.reject(Error(JSON.stringify(m.error))):p.resolve(m.result)}};
+ const call=(method,params={})=>new Promise((resolve,reject)=>{const key=++id;const timer=setTimeout(()=>{requests.delete(key);reject(Error('CDP timeout: '+method+' '+JSON.stringify(params)))},8000);requests.set(key,{resolve:v=>{clearTimeout(timer);resolve(v)},reject:e=>{clearTimeout(timer);reject(e)}});ws.send(JSON.stringify({id:key,method,params}))});
+ const run=async expression=>{const r=await call('Runtime.evaluate',{expression,returnByValue:true,awaitPromise:true});if(r.exceptionDetails)throw Error(JSON.stringify(r.exceptionDetails));return r.result?.value};
+ const key=async bytes=>{console.log('key',JSON.stringify(bytes));proc.terminal.write(bytes);await Bun.sleep(150)};
+ const click=async id=>{const r=await run("document.getElementById("+JSON.stringify(id)+").getBoundingClientRect().toJSON()");const col=Math.floor((r.x+r.width/2)/8)+1,row=Math.floor((r.y+r.height/2)/20)+2;await key('\x1b[<0;'+col+';'+row+'M');await key('\x1b[<0;'+col+';'+row+'m')};
+ const state=()=>run(`(()=>{const e=document.getElementById('field');return [e.value,e.selectionStart,e.selectionEnd]})()`);
+ await wait(async()=>await run("!!document.getElementById('field')"),'page loaded');
+ await wait(()=>rawFrames>0,'raw Kitty frame');console.log('page and raw frames ready');
+ await run("document.getElementById('field').focus()");
+ await key('\x01');assert.deepEqual((await state()).slice(1),[0,8]);
+ await key('\x1b[C');assert.deepEqual((await state()).slice(1),[8,8]);
+ await key('\x1b[1;2D');assert.deepEqual((await state()).slice(1),[7,8]);
+ await key('\x03');await wait(()=>readFileSync(clip,'utf8')==='z','Ctrl-C via browser xclip');
+ writeFileSync(clip,'貼上');await key('\x16');await wait(async()=>(await state())[0]==='abc中文xy貼上','Casty OSC52 paste');
+ assert.ok(oscReads>0);
+ await key('\x1b[1;2D');await key('\x18');await wait(async()=>(await state())[0]==='abc中文xy貼','Ctrl-X');assert.equal(readFileSync(clip,'utf8'),'上');
+ await run("document.getElementById('multi').focus();document.getElementById('multi').setSelectionRange(3,3)");
+ await key('\x1b[1;2B');assert.deepEqual(await run("[document.getElementById('multi').selectionStart,document.getElementById('multi').selectionEnd]"),[3,7]);
+ await click('write');
+ await wait(async()=>await run('globalThis.writeStatus')==='ok','navigator.writeText');assert.equal(readFileSync(clip,'utf8'),'navigator 中文');
+ await click('read');
+ await wait(async()=>await run('globalThis.readResult')==='navigator 中文','navigator.readText');
+ assert.equal(await run("navigator.clipboard.readText().then(()=> 'allowed',e=>e.name)"),'NotAllowedError');
+ await run("document.getElementById('field').focus();document.getElementById('field').setSelectionRange(1,1)");
+ await Bun.sleep(150);const a=await call('Page.captureScreenshot',{format:'png'});
+ await Bun.sleep(550);const b=await call('Page.captureScreenshot',{format:'png'});
+ assert.notEqual(a.data,b.data,'caret blink must change pixels');
+ writeFileSync(join(dir,'casty-page.png'),Buffer.from(a.data,'base64'));
+ const n=rawFrames;await run("document.body.style.background='#ffccdd'");await wait(()=>rawFrames>n,'updated terminal frame');
+ assert.ok(lastRaw.some(v=>v!==0));
+ console.log(JSON.stringify({root,dir,frames,rawFrames,oscReads,copyPaste:true,selection:true,caretMovement:true,caretBlink:true,navigatorReadWrite:true,rendering:true}));
+ await key('\x11');await Promise.race([proc.exited,Bun.sleep(2000)]);
+}finally{
+ ws?.close();if(proc&&proc.exitCode===null)proc.kill();proc?.terminal?.close();server.stop(true);
+ writeFileSync(join(dir,'terminal.log'),output);
+}

package/test/manual-double-click.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>雙擊測試 · ondblclick</title>
+<style>
+body{margin:0;padding:28px;background:#101c2c;color:#e9f2ff;font-family:sans-serif}
+h1{font-size:26px}p{line-height:1.6;color:#bed0e8}
+#target{display:block;width:100%;height:180px;background:#204763;color:white;border:2px solid #5ad5df;border-radius:12px;font-size:26px}
+#result{padding:18px;font-size:22px;color:#71edcf}
+#stats{padding:14px;background:#192b40;line-height:1.8}
+</style>
+<h1>雙擊才能開啟</h1>
+<p>在下面區域快速點兩下。單擊只更新紀錄，雙擊才會切換開啟／關閉狀態。</p>
+<button id="target" onclick="recordClick(event)" ondblclick="toggleDoor(event)">🔒 雙擊開啟</button>
+<div id="result">等待 dblclick…</div>
+<div id="stats">click：0　dblclick：0　最近 detail：0</div>
+<script>
+let clicks=0,doubles=0,opened=false;
+function stats(detail){document.getElementById('stats').textContent='click：'+clicks+'　dblclick：'+doubles+'　最近 detail：'+detail}
+function recordClick(e){clicks++;stats(e.detail)}
+function toggleDoor(e){doubles++;opened=!opened;document.getElementById('target').textContent=opened?'🔓 已開啟，雙擊關閉':'🔒 已關閉，雙擊開啟';document.getElementById('result').textContent='收到 ondblclick！第 '+doubles+' 次';stats(e.detail)}
+</script>

package/test/manual-flea-application.js

@@ -0,0 +1,49 @@
+// Run untouched Flea source through the browser's Wayland frontend, with an
+// isolated HOME/XDG state. Set FLEA_BIN to a real installed backend to exercise
+// filesystem operations. This script does not provide backend stubs.
+import { resolve, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { launch } from '../frontends/wayland/index.js';
+import { fleaSandbox } from './helpers/flea-sandbox.js';
+if (process.argv.some((arg) => arg === '-h' || arg === '--help')) {
+  console.log(`Usage: bun test/manual-flea-application.js
+
+Uses the current WAYLAND_DISPLAY / XDG_RUNTIME_DIR.
+BUNINU_FLEA_ROOT       Flea checkout (default ../flea)
+BUNINU_OMARCHY_ROOT    Omarchy checkout with shell/Commons and shell/Ui
+                      (default ../omarchy-qml-reference)
+FLEA_BIN              Optional real Flea backend executable
+
+Without FLEA_BIN, Flea shows its real backend-unavailable state. Settings,
+path entry, keyboard help and the network form can still be exercised.
+All application state is temporary and removed on exit.
+No dependencies are installed by this script.`);
+  process.exit(0);
+}
+const flea = resolve(process.env.BUNINU_FLEA_ROOT || '../flea'),
+  omarchy = resolve(
+    process.env.BUNINU_OMARCHY_ROOT || '../omarchy-qml-reference',
+  );
+for (const path of [
+  join(flea, 'ui/boot/shell.qml'),
+  join(omarchy, 'shell/Commons/qmldir'),
+  join(omarchy, 'shell/Ui/qmldir'),
+])
+  if (!existsSync(path)) throw Error('Missing source checkout: ' + path);
+const sandbox = fleaSandbox(flea, omarchy);
+let app;
+try {
+  app = await launch({
+    url: Bun.pathToFileURL(join(flea, 'ui/boot/shell.qml')).href,
+    width: 1000,
+    height: 720,
+  });
+  console.log('Unmodified Flea QML; isolated state: ' + sandbox.dir);
+  console.log('Backend: ' + sandbox.values.FLEA_BIN);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+    process.on(signal, () => app.close());
+  await app.done;
+} finally {
+  app?.close();
+  sandbox.close();
+}

package/test/manual-flea-binary.js

@@ -0,0 +1,62 @@
+// Run an installed, unmodified Flea executable through our opt-in qs wrapper.
+import { resolve, join } from 'node:path';
+import { existsSync, mkdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import { fleaSandbox } from './helpers/flea-sandbox.js';
+if (process.argv.some((arg) => ['-h', '--help'].includes(arg))) {
+  console.log(
+    `Usage: FLEA_BIN=/path/to/flea BUNINU_FLEA_ROOT=/path/to/share/flea bun test/manual-flea-binary.js\n\nUses the current Wayland socket. BUNINU_OMARCHY_ROOT defaults to ../omarchy-qml-reference.\nLaunches the actual binary with --gui; a temporary qs symlink selects lib/qml/qswayland through PATH.\nCreates an isolated HOME/XDG state with sample files; removes it on exit.\nNo dependencies are installed. The native Quickshell executable is not replaced.`,
+  );
+  process.exit(0);
+}
+const binary = process.env.FLEA_BIN && resolve(process.env.FLEA_BIN);
+const root = resolve(process.env.BUNINU_FLEA_ROOT || '../flea');
+const omarchy = resolve(
+  process.env.BUNINU_OMARCHY_ROOT || '../omarchy-qml-reference',
+);
+for (const path of [
+  binary,
+  join(root, 'ui/boot/shell.qml'),
+  join(omarchy, 'shell/Commons/qmldir'),
+  join(omarchy, 'shell/Ui/qmldir'),
+])
+  if (!path || !existsSync(path))
+    throw Error('Missing binary or QML imports: ' + path);
+const sandbox = fleaSandbox(root, omarchy);
+const wrapperDir = join(sandbox.dir, 'bin');
+mkdirSync(wrapperDir);
+symlinkSync(resolve('lib/qml/qswayland'), join(wrapperDir, 'qs'));
+mkdirSync(join(sandbox.values.HOME, 'Documents'));
+writeFileSync(
+  join(sandbox.values.HOME, 'hello.txt'),
+  'Official Flea backend, Buninu QML frontend.\n',
+);
+writeFileSync(
+  join(sandbox.values.HOME, 'Documents/inside.txt'),
+  'Directory navigation test.\n',
+);
+let child;
+const stop = () => child?.kill();
+try {
+  child = Bun.spawn([binary, '--gui', sandbox.values.HOME], {
+    env: {
+      ...process.env,
+      PATH: wrapperDir + ':' + process.env.PATH,
+      FLEA_UI: join(root, 'ui'),
+      QSG_RHI_BACKEND: 'opengl',
+    },
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  console.log(
+    'Official Flea -> qs (temporary symlink) -> Buninu qswayland. Temporary HOME: ' + sandbox.values.HOME,
+  );
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+    process.on(signal, stop);
+  process.exitCode = await child.exited;
+} finally {
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+    process.off(signal, stop);
+  child?.kill();
+  sandbox.close();
+}

package/test/manual-flea-qml.js

@@ -0,0 +1,9 @@
+// Manual, opt-in Wayland demo. Uses real QML imports, not injected JS globals.
+import {launch} from '../frontends/wayland/index.js';
+const url=new URL('./fixtures/qml/flea/demo.qml',import.meta.url).href;
+const app=await launch({url,width:640,height:400});
+try {
+  console.log('Flea EscapeHint: real component imports and a local test Theme.qml singleton (not full Flea).');
+  for(const signal of ['SIGINT','SIGTERM','SIGHUP'])process.on(signal,app.close);
+  await app.done;
+}finally{app.close();}

package/test/manual-flea-settings.js

@@ -0,0 +1,40 @@
+// Real upstream Theme, with isolated sample user data. No Flea/Commons stubs.
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { launch } from '../frontends/wayland/index.js';
+const fixture = new URL('./fixtures/qml/flea-theme/', import.meta.url);
+const home = mkdtempSync(join(tmpdir(), 'flea-settings-demo-'));
+const theme = join(home, '.local/state/omarchy/current/theme');
+mkdirSync(theme, { recursive: true });
+await Bun.write(
+  join(theme, 'colors.toml'),
+  'background = "#101315"\nforeground = "#eeeeee"\naccent = "#70e1e8"\nred = "#ff3333"\n',
+);
+await Bun.write(join(theme, 'shell.toml'), '[font]\nbase-size = 14\n');
+await Bun.write(join(theme, '../theme.name'), 'demo');
+const oldHome = process.env.HOME,
+  oldImports = process.env.QML_IMPORT_PATH;
+process.env.HOME = home;
+process.env.QML_IMPORT_PATH = Bun.fileURLToPath(new URL('imports/', fixture));
+let app;
+try {
+  app = await launch({
+    url: new URL('settings.qml', fixture).href,
+    width: 800,
+    height: 420,
+  });
+  console.log(
+    'Real Flea SettingsRuler + Theme; isolated sample data: ' + home,
+  );
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+    process.on(signal, () => app.close());
+  await app.done;
+} finally {
+  app?.close();
+  if (oldHome === undefined) delete process.env.HOME;
+  else process.env.HOME = oldHome;
+  if (oldImports === undefined) delete process.env.QML_IMPORT_PATH;
+  else process.env.QML_IMPORT_PATH = oldImports;
+  rmSync(home, { recursive: true, force: true });
+}

package/test/manual-flea-theme.js

@@ -0,0 +1,40 @@
+// Real upstream Theme, with isolated sample user data. No Flea/Commons stubs.
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { launch } from '../frontends/wayland/index.js';
+const fixture = new URL('./fixtures/qml/flea-theme/', import.meta.url);
+const home = mkdtempSync(join(tmpdir(), 'flea-theme-demo-'));
+const theme = join(home, '.local/state/omarchy/current/theme');
+mkdirSync(theme, { recursive: true });
+await Bun.write(
+  join(theme, 'colors.toml'),
+  'background = "#101315"\nforeground = "#eeeeee"\naccent = "#70e1e8"\nred = "#ff3333"\n',
+);
+await Bun.write(join(theme, 'shell.toml'), '[font]\nbase-size = 14\n');
+await Bun.write(join(theme, '../theme.name'), 'demo');
+const oldHome = process.env.HOME,
+  oldImports = process.env.QML_IMPORT_PATH;
+process.env.HOME = home;
+process.env.QML_IMPORT_PATH = Bun.fileURLToPath(new URL('imports/', fixture));
+let app;
+try {
+  app = await launch({
+    url: new URL('demo.qml', fixture).href,
+    width: 800,
+    height: 900,
+  });
+  console.log(
+    'Real Flea Theme + Omarchy Commons; isolated sample data: ' + home,
+  );
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'])
+    process.on(signal, () => app.close());
+  await app.done;
+} finally {
+  app?.close();
+  if (oldHome === undefined) delete process.env.HOME;
+  else process.env.HOME = oldHome;
+  if (oldImports === undefined) delete process.env.QML_IMPORT_PATH;
+  else process.env.QML_IMPORT_PATH = oldImports;
+  rmSync(home, { recursive: true, force: true });
+}

package/test/manual-mouse-buttons.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="zh-Hant"><meta charset="utf-8"><title>滑鼠按鍵測試</title>
+<style>
+body{margin:0;padding:28px;background:#101a28;color:#e1f2ff;font-family:sans-serif}
+h1{font-size:28px}p{line-height:1.6}button{display:block;width:100%;height:220px;background:#146d83;color:white;border:3px solid #62dbe9;border-radius:18px;font-size:34px;font-weight:bold}
+#result{margin-top:24px;font-size:27px;color:#70efce}#counts{font-size:22px}pre{white-space:pre-wrap;background:#19283b;padding:16px;font-size:17px}
+</style>
+<h1>左鍵・右鍵・中鍵測試</h1><p>直接點按測左鍵。長按圖片，選 Right click 測右鍵。右鍵不應增加左鍵次數。</p>
+<button id="pad">在這裡點擊 / 長按</button><div id="result">等待按鍵…</div><p id="counts">左鍵 0 ｜ 右鍵 0 ｜ 中鍵 0</p><pre id="events">事件記錄</pre>
+<script>
+const pad=document.getElementById('pad'),result=document.getElementById('result'),counts=document.getElementById('counts'),log=document.getElementById('events');
+const totals=[0,0,0],names=['左鍵','中鍵','右鍵'];let rows=[];
+for(const type of ['mousedown','contextmenu','mouseup','click','auxclick'])pad.addEventListener(type,e=>{
+ if(type==='contextmenu')e.preventDefault();
+ rows.unshift(type+' button='+e.button+' buttons='+e.buttons);rows=rows.slice(0,10);log.textContent=rows.join('\n');
+ if(type==='click'||type==='auxclick'){totals[e.button]++;result.textContent='收到：'+names[e.button];counts.textContent='左鍵 '+totals[0]+' ｜ 右鍵 '+totals[2]+' ｜ 中鍵 '+totals[1];}
+});
+</script></html>

package/test/manual-omastorm-engine.mjs

@@ -0,0 +1,19 @@
+// Requires an already-running official engine; never starts or installs one.
+import {mkdtemp,rm} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {createBrowser} from '../lib/headless-shell.js';
+const root=resolve(process.argv[2] || '../omastorm');
+const dir=await mkdtemp('/tmp/omastorm-engine-probe-');
+await Bun.write(dir+'/probe.qml',`import QtQuick
+import ${JSON.stringify(pathToFileURL(root+'/ui').href)} as Storm
+Item {Storm.Engine {id:engine} Component.onCompleted:globalThis.engineProbe=engine}`);
+const browser=await createBrowser({spareRenderer:false});
+try {
+ await browser.context.navigate(pathToFileURL(dir+'/probe.qml').href);
+ for(let i=0;i<100;i++){
+  const value=await browser.context.evaluate('globalThis.engineProbe ? {error:engineProbe.error, sites:engineProbe.sites.length,state:engineProbe.state?.type,frame:engineProbe.state?.frame?.kind} : {text:document.body.textContent.slice(0,1000)}');
+  if(value?.state || value?.error || value?.text){console.log(JSON.stringify(value));break;}
+  await Bun.sleep(50);
+ }
+}finally{browser.close();await rm(dir,{recursive:true,force:true});}