buninu-browser 0.2.3 → 0.2.4

package/test/network-service.test.js

@@ -53,6 +53,142 @@ afterAll(() => server?.stop(true));
 const local = (path) => `http://localhost:${server.port}${path}`;
 const loopback = (path) => `http://127.0.0.1:${server.port}${path}`;
 
+test("navigation metadata distinguishes browser UI from page-initiated navigation", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    calls.push({ url, headers: new Headers(init.headers) });
+    return url.endsWith("/start") ? new Response(null, { status: 302, headers: { location: "https://other.test/end" } })
+      : new Response("ok");
+  } });
+  await network.navigate("https://example.test/start");
+  for (const { headers } of calls) {
+    expect(headers.get("sec-fetch-mode")).toBe("navigate");
+    expect(headers.get("sec-fetch-dest")).toBe("document");
+    expect(headers.get("sec-fetch-site")).toBe("none");
+    expect(headers.has("sec-fetch-user")).toBeFalse();
+  }
+  calls.length = 0;
+  await network.navigate("https://example.test/end", { referrer: "https://example.test/page#section" });
+  expect(calls[0].headers.get("sec-fetch-site")).toBe("same-origin");
+  expect(calls[0].headers.get("referer")).toBe("https://example.test/page");
+  await network.navigate("https://example.test:8443/end", { referrer: "https://example.test/page" });
+  expect(calls[1].headers.get("sec-fetch-site")).toBe("same-site");
+  expect(calls[1].headers.get("referer")).toBe("https://example.test/");
+});
+
+test("resource destinations are separated while referrer-independent cache entries survive navigation", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    const headers = new Headers(init.headers);
+    calls.push(headers);
+    return new Response(headers.get("sec-fetch-dest"), { headers: { "cache-control": "max-age=60" } });
+  } });
+  await network.subresource("https://example.test/asset", "https://example.test/page", "script");
+  await network.subresource("https://example.test/asset", "https://example.test/page", "image");
+  await network.subresource("https://example.test/asset", "https://example.test/other", "image");
+  await network.subresource("https://example.test/asset", "https://example.test/other", "image");
+  expect(calls).toHaveLength(2);
+  expect(calls.map(headers => headers.get("sec-fetch-dest"))).toEqual(["script", "image"]);
+  expect(calls[0].get("sec-fetch-mode")).toBe("no-cors");
+  expect(calls[1].get("referer")).toBe("https://example.test/page");
+});
+
+test("Vary: Referer isolates representations and validators across documents", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    const headers = new Headers(init.headers); calls.push(headers);
+    return new Response(headers.get("referer"), { headers: { "cache-control": "max-age=60", vary: "Referer", etag: '"page"' } });
+  } });
+  await network.subresource("https://example.test/image", "https://example.test/one", "image");
+  const other = await network.subresource("https://example.test/image", "https://example.test/two", "image");
+  await network.subresource("https://example.test/image", "https://example.test/two", "image");
+  expect(calls).toHaveLength(2);
+  expect(calls[1].has("if-none-match")).toBeFalse();
+  expect(new TextDecoder().decode(other.body)).toBe("https://example.test/two");
+});
+
+test("a cacheable final body does not cache a credential-dependent redirect", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    calls.push(url);
+    if (url.endsWith('/entry')) return new Response(null, { status:302, headers:{location:'https://asset.test/final', 'cache-control':'no-store'} });
+    return new Response(new Headers(init.headers).get('cookie') ?? 'anonymous', { headers:{'cache-control':'max-age=60'} });
+  }});
+  expect(new TextDecoder().decode((await network.subresource('https://page.test/entry','https://page.test/')).body)).toBe('anonymous');
+  network.setDocumentCookie('https://asset.test/','session=changed; SameSite=None; Secure');
+  expect(new TextDecoder().decode((await network.subresource('https://page.test/entry','https://page.test/')).body)).toBe('session=changed');
+  expect(calls.length).toBe(4);
+});
+
+test("CORS header value rules distinguish simple values from preflighted ones", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    const headers = new Headers(init.headers); calls.push({method:init.method, headers});
+    return new Response('ok', {headers:{'access-control-allow-origin':'*','access-control-allow-headers':'*','access-control-max-age':'0'}});
+  }});
+  const check = async (name, value, preflight) => {
+    calls.length = 0;
+    await network.pageFetch({url:'https://asset.test/api', headers:[[name,value]]},'https://page.test/');
+    expect(calls.map(call=>call.method)).toEqual(preflight ? ['OPTIONS','GET'] : ['GET']);
+    if (preflight) expect(calls[0].headers.get('access-control-request-headers')).toBe(name);
+  };
+  await check('accept','text/html, */*;q=0.8',false);
+  await check('accept','text/html;variant="wide"',true);
+  await check('accept-language','en-US, zh-TW;q=0.8',false);
+  await check('accept-language','en_US',true);
+  await check('content-type','text/plain;charset=utf-8',false);
+  await check('content-type','text/plain;charset="utf-8"',true);
+  await check('content-type','text/plain;'+ 'a'.repeat(128),true);
+  await check('range','bytes=0-99',false);
+  await check('range','bytes=100-',false);
+  await check('range','bytes=-99',true);
+  await check('range','bytes=100-99',true);
+  await check('range','bytes=0-99,200-299',true);
+  calls.length=0;
+  await network.pageFetch({url:'https://page.test/api',mode:'no-cors',headers:[['range','bytes=0-99'],['accept-language','en_US'],['accept','text/plain']]},'https://page.test/');
+  expect(calls[0].headers.get('range')).toBeNull();
+  expect(calls[0].headers.get('accept-language')).toBeNull();
+  expect(calls[0].headers.get('accept')).toBe('text/plain');
+});
+
+test("Fetch Metadata is trustworthy-only and cannot be forged by page headers", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    calls.push(new Headers(init.headers));
+    return new Response("ok");
+  } });
+  await network.pageFetch({ url: "https://example.test/api", mode: "same-origin",
+    headers: [["sec-fetch-mode", "navigate"], ["sec-fetch-site", "none"], ["sec-fetch-user", "?1"]] }, "https://example.test/page");
+  expect(calls[0].get("sec-fetch-mode")).toBe("same-origin");
+  expect(calls[0].get("sec-fetch-site")).toBe("same-origin");
+  expect(calls[0].get("sec-fetch-dest")).toBe("empty");
+  expect(calls[0].has("sec-fetch-user")).toBeFalse();
+  await network.navigate("http://example.test/page");
+  expect(calls[1].has("sec-fetch-mode")).toBeFalse();
+  await network.navigate("http://localhost/page");
+  expect(calls[2].get("sec-fetch-mode")).toBe("navigate");
+});
+
+test("a redirect cannot regain same-origin metadata or leak a full referrer", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    calls.push(new Headers(init.headers));
+    const redirects = { "https://example.test/start": "http://localhost/middle", "http://localhost/middle": "https://example.test/end" };
+    return redirects[url] ? new Response(null, { status: 302, headers: { location: redirects[url] } }) : new Response("ok");
+  } });
+  await network.navigate("https://example.test/start", { referrer: "https://example.test/private#anchor" });
+  expect(calls.map(headers => headers.get("sec-fetch-site"))).toEqual(["same-origin", "cross-site", "cross-site"]);
+  // Loopback HTTP is potentially trustworthy. A cross-origin hop trims the
+  // path; returning to the original origin must not restore it.
+  expect(calls[1].get("referer")).toBe("https://example.test/");
+  expect(calls[2].get("referer")).toBe("https://example.test/");
+  calls.length = 0;
+  await network.navigate("https://other.test/end", { post: { body: "a=b", contentType: "application/x-www-form-urlencoded",
+    referrer: "https://example.test/private#anchor" } });
+  expect(calls[0].get("referer")).toBe("https://example.test/");
+  expect(calls[0].get("origin")).toBe("https://example.test");
+});
+
 test("follows redirects by hand and stores cookies on every hop", async () => {
   seen = [];
   const network = new NetworkService();
@@ -293,3 +429,255 @@ test("/json/new opens a target on PUT only", async () => {
     cdp.stop(true);
   }
 });
+
+test("revalidation updates cached headers and validator; no-cache overrides max-age", async () => {
+  const validators = [];
+  const network = new NetworkService({ fetch: async (_, init) => {
+    const etag = new Headers(init.headers).get('if-none-match'); validators.push(etag);
+    if (validators.length === 1) return new Response('body', { headers: { etag: '"v1"', 'cache-control': 'max-age=60, no-cache' } });
+    return new Response(null, { status: 304, headers: { etag: '"v2"', 'x-version': '2' } });
+  } });
+  for (let i = 0; i < 3; i++) {
+    const r = await network.subresource('https://a.test/style.css','https://a.test/');
+    expect(new TextDecoder().decode(r.body)).toBe('body');
+    if (i) expect(r.headers).toContainEqual(['x-version','2']);
+  }
+  expect(validators).toEqual([null,'"v1"','"v2"']);
+});
+
+test("Last-Modified validates without ETag; Vary:* and no-store responses are never retained", async () => {
+  const seen = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    seen.push([url,new Headers(init.headers).get('if-modified-since')]);
+    if (url.endsWith('/modified')) return new Response('x',{headers:{'last-modified':'Wed, 01 Jan 2025 00:00:00 GMT'}});
+    return new Response('x',{headers:{'cache-control':url.endsWith('/star')?'max-age=60':'no-store, max-age=60',vary:'*'}});
+  } });
+  for (const path of ['modified','star','store']) for(let i=0;i<2;i++)await network.subresource(`https://a.test/${path}`,'https://a.test/');
+  expect(seen).toHaveLength(6);
+  expect(seen[1][1]).toBe('Wed, 01 Jan 2025 00:00:00 GMT');
+});
+
+test("cache byte budget evicts least-recently-used data and does not retain oversized bodies", async () => {
+  const calls=[];
+  const network=new NetworkService({maxSubresourceCacheBytes:8,fetch:async url=>{
+    calls.push(url);return new Response(url.endsWith('/large')?'0123456789':'1234',{headers:{'cache-control':'max-age=60'}});
+  }});
+  const get=path=>network.subresource('https://a.test/'+path,'https://a.test/');
+  await get('a');await get('b');await get('a');await get('c');await get('a');await get('b');
+  expect(calls.map(u=>u.split('/').at(-1))).toEqual(['a','b','c','b']);
+  await get('large');await get('large');expect(calls.filter(u=>u.endsWith('/large'))).toHaveLength(2);
+});
+
+test("Age and Date reduce freshness, and immutable alone does not invent a lifetime", async () => {
+  let calls=0;
+  const network=new NetworkService({fetch:async url=>{
+    calls++;return new Response('x',{headers:url.endsWith('/immutable')?{'cache-control':'immutable'}:{'cache-control':'max-age=60',age:'120'}});
+  }});
+  for(const path of ['aged','immutable'])for(let i=0;i<2;i++)await network.subresource(`https://a.test/${path}`,'https://a.test/');
+  expect(calls).toBe(4);
+});
+
+test("aborting a queued page fetch releases it without waiting for busy host slots", async () => {
+  const gates=[];const calls=[];
+  const network=new NetworkService({fetch:async url=>{
+    calls.push(url);await new Promise(resolve=>gates.push(resolve));return new Response('ok');
+  }});
+  const document='https://busy.test/';
+  const active=Array.from({length:6},(_,i)=>network.pageFetch({url:document+i},document));
+  while(gates.length<6)await Bun.sleep(1);
+  const controller=new AbortController();
+  const queued=network.pageFetch({url:document+'aborted'},document,{signal:controller.signal});
+  controller.abort(new Error('cancelled navigation'));
+  await expect(queued).rejects.toThrow('cancelled navigation');
+  expect(calls).toHaveLength(6);
+  for(const finish of gates)finish();await Promise.all(active);
+  expect(calls.some(url=>url.endsWith('/aborted'))).toBe(false);
+});
+
+test("successful CORS preflights reuse permission without caching API responses or crossing origins", async () => {
+  const calls=[];
+  const network=new NetworkService({fetch:async (url,init)=>{
+    const headers=new Headers(init.headers);calls.push([url,init.method,headers.get('access-control-request-headers')]);
+    return new Response(init.method==='OPTIONS'?null:'live '+calls.length,{headers:{
+      'access-control-allow-origin':headers.get('origin'), 'access-control-allow-credentials':'true',
+      'access-control-allow-methods':'PUT, DELETE','access-control-allow-headers':'x-token,x-extra',
+      'access-control-max-age':'60',
+    }});
+  }});
+  const request={url:'https://api.test/items',method:'PUT',headers:[['x-token','one']]};
+  const first=await network.pageFetch(request,'https://page.test/');
+  const second=await network.pageFetch({...request,headers:[['x-token','two']]},'https://page.test/next');
+  expect(new TextDecoder().decode(first.body)).not.toBe(new TextDecoder().decode(second.body));
+  expect(calls.map(c=>c[1])).toEqual(['OPTIONS','PUT','PUT']);
+  await network.pageFetch(request,'https://other.test/');
+  await network.pageFetch({...request,credentials:'include'},'https://page.test/');
+  await network.pageFetch({...request,url:request.url+'/other'},'https://page.test/');
+  await network.pageFetch({...request,method:'DELETE'},'https://page.test/');
+  await network.pageFetch({...request,headers:[...request.headers,['x-extra','value']]},'https://page.test/');
+  expect(calls.filter(c=>c[1]==='OPTIONS')).toHaveLength(6);
+});
+
+test("CORS preflight grants expire and max-age zero does not cache", async () => {
+  let preflights=0;
+  const network=new NetworkService({fetch:async (url,init)=>{
+    if(init.method==='OPTIONS')preflights++;
+    return new Response(null,{headers:{'access-control-allow-origin':'*','access-control-allow-methods':'PUT',
+      'access-control-max-age':url.endsWith('zero')?'0':'1'}});
+  }});
+  const get=path=>network.pageFetch({url:'https://api.test/'+path,method:'PUT'},'https://page.test/');
+  await get('one');await get('one');expect(preflights).toBe(1);
+  await Bun.sleep(1050);await get('one');expect(preflights).toBe(2);
+  await get('zero');await get('zero');expect(preflights).toBe(4);
+});
+
+test("wildcard CORS permissions do not authorize Authorization, and denied grants are not cached", async () => {
+  let calls=0;
+  const network=new NetworkService({fetch:async()=>{calls++;return new Response(null,{headers:{
+    'access-control-allow-origin':'*','access-control-allow-headers':'*','access-control-max-age':'60',
+  }});}});
+  const request={url:'https://api.test/',headers:[['Authorization','Bearer example']]};
+  for(let i=0;i<2;i++)await expect(network.pageFetch(request,'https://page.test/')).rejects.toThrow('does not allow header authorization');
+  expect(calls).toBe(2);
+});
+
+test("an aborted CORS preflight does not send the API request or cache a grant",async()=>{
+  let calls=0;
+  const network=new NetworkService({fetch:async(_,init)=>{
+    calls++;await new Promise((resolve,reject)=>init.signal.addEventListener('abort',()=>reject(init.signal.reason),{once:true}));
+  }});
+  const controller=new AbortController();
+  const pending=network.pageFetch({url:'https://api.test/',method:'PUT'},'https://page.test/',{signal:controller.signal});
+  while(calls===0)await Bun.sleep(1);
+  controller.abort(new Error('cancelled preflight'));
+  await expect(pending).rejects.toThrow('cancelled preflight');expect(calls).toBe(1);
+});
+
+test("aborting a preflight after headers arrive does not retain its permission grant", async () => {
+  const calls = [];
+  let headersArrived = false;
+  const network = new NetworkService({ fetch: async (url, init) => {
+    calls.push(init.method);
+    const body = calls.length === 1 ? new ReadableStream({ start(controller) {
+      headersArrived = true;
+      init.signal.addEventListener('abort', () => controller.error(init.signal.reason), {once:true});
+    }}) : null;
+    return new Response(body,{headers:{'access-control-allow-origin':'*','access-control-allow-methods':'PUT','access-control-max-age':'60'}});
+  }});
+  const controller = new AbortController();
+  const request = {url:'https://api.test/',method:'PUT'};
+  const pending = network.pageFetch(request,'https://page.test/',{signal:controller.signal});
+  while (!headersArrived) await Bun.sleep(1);
+  controller.abort(new Error('cancelled after headers'));
+  await expect(pending).rejects.toThrow('cancelled after headers');
+  await network.pageFetch(request,'https://page.test/');
+  expect(calls).toEqual(['OPTIONS','OPTIONS','PUT']);
+});
+
+test("same-origin fetch redirects still enforce CORS, credentials and response-header filtering", async () => {
+  const calls = [];
+  let allowed = false;
+  const network = new NetworkService({ fetch: async (url, init) => {
+    const headers = new Headers(init.headers); calls.push({ url, headers });
+    if (url === "https://source.test/start") return new Response(null, { status: 302, headers: { location: "https://target.test/data" } });
+    return new Response("public", { headers: { ...(allowed ? { "access-control-allow-origin": "https://source.test" } : {}),
+      "x-secret": "hidden", "x-public": "visible", "access-control-expose-headers": "x-public" } });
+  } });
+  network.cookies.store("https://target.test/", ["secret=credential; Secure; SameSite=None"]);
+  await expect(network.pageFetch({ url: "https://source.test/start" }, "https://source.test/page")).rejects.toThrow("CORS");
+  expect(calls[1].headers.get("cookie")).toBeNull();
+  expect(calls[1].headers.get("origin")).toBe("https://source.test");
+  allowed = true;
+  const response = await network.pageFetch({ url: "https://source.test/start" }, "https://source.test/page");
+  expect(response.type).toBe("cors");
+  expect(new Headers(response.headers).get("x-secret")).toBeNull();
+  expect(new Headers(response.headers).get("x-public")).toBe("visible");
+});
+
+test("same-origin mode blocks a cross-origin redirect before contacting its target", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async url => {
+    calls.push(url);
+    return new Response(null, { status: 302, headers: { location: "https://target.test/private" } });
+  } });
+  await expect(network.pageFetch({ url: "https://source.test/start", mode: "same-origin" }, "https://source.test/page"))
+    .rejects.toThrow("mode is same-origin");
+  expect(calls).toEqual(["https://source.test/start"]);
+});
+
+test("no-cors fetches become opaque when a redirect crosses origins", async () => {
+  const network = new NetworkService({ fetch: async url => url.includes("source.test")
+    ? new Response(null, { status: 302, headers: { location: "https://target.test/private" } })
+    : new Response("private", { headers: { "x-private": "secret" } }) });
+  const result = await network.pageFetch({ url: "https://source.test/start", mode: "no-cors" }, "https://source.test/page");
+  expect(result).toMatchObject({ type: "opaque", status: 0, url: "", headers: [], redirected: false });
+  expect(result.body.byteLength).toBe(0);
+});
+
+test("redirected non-simple requests preflight the new origin and strip Authorization", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    const headers = new Headers(init.headers); calls.push({ url, method: init.method, headers });
+    if (url.includes("source.test")) return new Response(null, { status: 307, headers: { location: "https://target.test/api" } });
+    return new Response(null, { status: 204, headers: { "access-control-allow-origin": "https://source.test",
+      "access-control-allow-methods": "PUT", "access-control-allow-headers": "x-custom" } });
+  } });
+  await network.pageFetch({ url: "https://source.test/start", method: "PUT", body: new TextEncoder().encode("body"),
+    headers: [["authorization", "Bearer private"], ["x-custom", "value"]] }, "https://source.test/page");
+  expect(calls.map(call => call.method)).toEqual(["PUT", "OPTIONS", "PUT"]);
+  expect(calls[0].headers.get("authorization")).toBe("Bearer private");
+  expect(calls[1].headers.get("access-control-request-headers")).toBe("x-custom");
+  expect(calls[2].headers.has("authorization")).toBeFalse();
+});
+
+test("a cross-origin redirect chain checks each hop and taints subsequent Origin", async () => {
+  const calls = [];
+  const network = new NetworkService({ fetch: async (url, init) => {
+    const headers = new Headers(init.headers); calls.push({ url, headers });
+    if (url === "https://target.test/start") return new Response(null, { status: 302, headers: {
+      location: "https://final.test/end", "access-control-allow-origin": "https://source.test" } });
+    return new Response("done", { headers: { "access-control-allow-origin": "null" } });
+  } });
+  const result = await network.pageFetch({ url: "https://target.test/start" }, "https://source.test/page");
+  expect(result.type).toBe("cors");
+  expect(calls.map(call => call.headers.get("origin"))).toEqual(["https://source.test", "null"]);
+});
+
+test("canceling one coalesced resource consumer preserves other consumers", async () => {
+  let requests = 0, underlyingAborted = false, complete;
+  const network = new NetworkService({ fetch: async (url, init) => {
+    requests++;
+    return new Promise((resolve, reject) => {
+      complete = () => resolve(new Response("shared image"));
+      init.signal.addEventListener("abort", () => { underlyingAborted = true; reject(init.signal.reason); }, { once: true });
+    });
+  } });
+  const first = new AbortController(), second = new AbortController();
+  const one = network.subresource("https://example.test/image", "https://example.test/page", "image", { signal: first.signal });
+  const two = network.subresource("https://example.test/image", "https://example.test/page", "image", { signal: second.signal });
+  await Bun.sleep(0);
+  first.abort("first document closed");
+  await expect(one).rejects.toBe("first document closed");
+  expect(underlyingAborted).toBeFalse();
+  complete();
+  expect(new TextDecoder().decode((await two).body)).toBe("shared image");
+  expect(requests).toBe(1);
+  expect(underlyingAborted).toBeFalse();
+});
+
+test("the last resource consumer aborts its transfer and a later consumer starts fresh", async () => {
+  let requests = 0, aborts = 0;
+  const network = new NetworkService({ fetch: async (url, init) => {
+    if (++requests === 2) return new Response("fresh");
+    return new Promise((resolve, reject) => init.signal.addEventListener("abort", () => {
+      aborts++; reject(init.signal.reason);
+    }, { once: true }));
+  } });
+  const controller = new AbortController();
+  const pending = network.subresource("https://example.test/image", "https://example.test/page", "image", { signal: controller.signal });
+  await Bun.sleep(0);
+  controller.abort("document closed");
+  await expect(pending).rejects.toBe("document closed");
+  const fresh = await network.subresource("https://example.test/image", "https://example.test/page", "image");
+  expect(new TextDecoder().decode(fresh.body)).toBe("fresh");
+  expect([requests, aborts]).toEqual([2, 1]);
+});

package/test/page-scripts.test.js

@@ -1216,7 +1216,7 @@ test("ES modules: graphs, live exports, JSON, import.meta, dynamic import, TLA,
   await load(`
     <script type="importmap">{ "imports": { "cdn-lib": "https://cdn.test/lib/index.js" } }</script>
     <script type="module" src="/modules/main.js"></script>
-    <script type="module">window.inlineModule = import.meta.url.includes('#inline-module');</script>`);
+    <script type="module">window.inlineModule = import.meta.url === document.baseURI;</script>`);
   expect(await evaluate("moduleResult")).toBe([
     // Imports are live bindings, named and namespace alike.
     "named:2", "namespace:2", "twice:42", "json:42", "loaded lazily from lazy.js",

package/test/paint-frame.test.js

@@ -0,0 +1,103 @@
+import { expect, test } from 'bun:test';
+import { cropViewport, encodeImage, encodeImageBase64 } from '../lib/paint/frame.js';
+import { FrameCaptureCache } from '../lib/paint/frame-cache.js';
+import { appendParagraphText } from '../lib/paint/paragraph-text.js';
+
+function numberedTile() {
+  const bytes = new Uint8Array(7 + 3 * 4 * 4);
+  const pixels = bytes.subarray(7);
+  for (let i = 0; i < 12; i++) pixels.set([i + 1, 20, 30, 255], i * 4);
+  return { pixels, pixelWidth: 3, pixelHeight: 4, x: 0, y: 10, width: 3, height: 4, scale: 1,
+    background: [99, 0, 0, 128] };
+}
+const reds = (pixels) => Array.from({ length: pixels.length / 4 }, (_, i) => pixels[i * 4]);
+
+test('full-width viewport crops reuse immutable tile bytes and respect the source byte offset', () => {
+  const tile = numberedTile();
+  const result = cropViewport(tile, 0, 11, 3, 2);
+  expect(result.pixels.buffer).toBe(tile.pixels.buffer);
+  expect(reds(result.pixels)).toEqual([4, 5, 6, 7, 8, 9]);
+  expect(result.width).toBe(3);
+  expect(result.height).toBe(2);
+  expect(reds(cropViewport(tile, 0, 10, 3, 4).pixels)).toEqual(reds(tile.pixels));
+});
+
+test('partial crops preserve columns, background alpha, and scaled outside rows', () => {
+  const tile = numberedTile();
+  expect(reds(cropViewport(tile, 1, 11, 2, 2).pixels)).toEqual([5, 6, 8, 9]);
+  const clipped = cropViewport(tile, -1, 9, 4, 3);
+  expect(reds(clipped.pixels)).toEqual([99, 99, 99, 99, 99, 1, 2, 3, 99, 4, 5, 6]);
+  expect([...clipped.pixels.subarray(0, 4)]).toEqual([99, 0, 0, 128]);
+  const scaled = { ...tile, scale: 2, width: 1.5, height: 2 };
+  expect(reds(cropViewport(scaled, 0.5, 10.5, 1, 1).pixels)).toEqual([5, 6, 8, 9]);
+});
+
+test('native base64 capture preserves PNG and JPEG bytes', async () => {
+  const tile = numberedTile();
+  for (const format of ['png', 'jpeg', 'webp']) {
+    const bytes = await encodeImage(tile.pixels, 3, 4, { format, quality: 85 });
+    const base64 = await encodeImageBase64(tile.pixels, 3, 4, { format, quality: 85 });
+    expect(Buffer.from(base64, 'base64')).toEqual(Buffer.from(bytes));
+  }
+});
+
+test('encoding releases only its temporary bytes on success and failure', async () => {
+  const pixels = new Uint8Array([5, 10, 15, 255]);
+  const expected = [...pixels];
+  const encoded = await encodeImage(pixels, 1, 1);
+  expect(encoded.byteLength).toBeGreaterThan(0);
+  expect([...pixels]).toEqual(expected);
+  await expect(encodeImage(pixels, 100, 100)).rejects.toThrow();
+  expect([...pixels]).toEqual(expected);
+  expect((await new Bun.Image(encoded).metadata()).width).toBe(1);
+});
+
+test('simultaneous captures share work and an older completion cannot replace the latest frame', async () => {
+  const cache = new FrameCaptureCache();
+  let completeOld;
+  let captures = 0;
+  const first = cache.get('old', () => { captures++; return new Promise(resolve => { completeOld = resolve; }); });
+  expect(cache.get('old', () => { captures++; })).toBe(first);
+  expect(captures).toBe(1);
+  const second = cache.get('new', () => 'new frame');
+  expect(await second).toBe('new frame');
+  completeOld('old frame');
+  expect(await first).toBe('old frame');
+  expect(cache.get('new', () => { throw new Error('must retain new'); })).toBe(second);
+});
+
+test('capture failures allow retry without discarding a newer frame', async () => {
+  const cache = new FrameCaptureCache();
+  await expect(cache.get('bad', () => { throw new Error('encode failed'); })).rejects.toThrow('encode failed');
+  expect(await cache.get('bad', () => 'retry')).toBe('retry');
+  let fail;
+  const pending = cache.get('old', () => new Promise((_, reject) => { fail = reject; }));
+  const next = cache.get('new', () => 'new');
+  fail(new Error('old failed'));
+  await expect(pending).rejects.toThrow('old failed');
+  expect(cache.get('new', () => 'wrong')).toBe(next);
+});
+
+function textRuns(text) {
+  let emoji = false;
+  const runs = [];
+  appendParagraphText({
+    addText: text => runs.push({ text, emoji }),
+    pushStyle: () => { emoji = true; },
+    pop: () => { emoji = false; },
+  }, text, () => ({}));
+  return runs;
+}
+
+test('paragraphs batch ordinary text while preserving whole emoji graphemes and fallback boundaries', () => {
+  const ordinary = 'Latin office العربية हिन्दी 中文 e\u0301 ';
+  expect(textRuns(ordinary)).toEqual([{ text: ordinary, emoji: false }]);
+  expect(textRuns('')).toEqual([{ text: ' ', emoji: false }]);
+  const emojis = ['👨‍👩‍👧‍👦', '❤️', '🇹🇼', '1️⃣', '👍🏽'];
+  const mixed = `${ordinary}${emojis.join(' + ')} end`;
+  const runs = textRuns(mixed);
+  expect(runs.map(run => run.text).join('')).toBe(mixed);
+  expect(runs.filter(run => run.emoji).map(run => run.text)).toEqual(emojis);
+  expect(runs[0].text).toBe(ordinary);
+  expect(runs.at(-1)).toEqual({ text: ' end', emoji: false });
+});

package/test/paint-paragraph-cache.test.js

@@ -0,0 +1,87 @@
+import { expect, test } from "bun:test";
+import { createPageRenderer, loadGraphics } from "../lib/renderer/page-renderer.js";
+
+test("scroll paints reuse shaped text, evict bounded resources, and release paragraphs on navigation/disposal", async () => {
+  const { CanvasKit } = await loadGraphics();
+  const original = CanvasKit.ParagraphBuilder.MakeFromFontCollection;
+  let built = 0;
+  let alive = 0;
+  CanvasKit.ParagraphBuilder.MakeFromFontCollection = (...args) => {
+    const builder = original(...args);
+    const build = builder.build.bind(builder);
+    builder.build = () => {
+      const paragraph = build();
+      const dispose = paragraph.delete.bind(paragraph);
+      built++;
+      alive++;
+      paragraph.delete = () => { alive--; dispose(); };
+      return paragraph;
+    };
+    return builder;
+  };
+  let renderer;
+  try {
+    renderer = await createPageRenderer({ fetchResource: async url => ({ ok: false, status: 404, url, body: new Uint8Array() }) });
+    renderer.resize(400, 200, 1);
+    await renderer.loadDocument({ url: "https://paint.test/", status: 200, contentType: "text/html",
+      source: `<!doctype html><style>body { margin:0 } p { margin:0; height:30px }</style>${
+        Array.from({ length: 400 }, (_, i) => `<p>Article number ${i}: shared text</p>`).join("")}` });
+    await renderer.whenLoaded();
+    const first = await renderer.screenshot();
+    const before = built;
+    renderer.scroll(0, 1);
+    await renderer.screenshot();
+    // No layout invalidation and the same seven visible paragraph items.
+    expect(built - before).toBeLessThanOrEqual(1);
+    renderer.scroll(0, -1);
+    expect(await renderer.screenshot()).toBe(first);
+    // A fresh layout/display list still uses identical text shaping inputs.
+    const beforeLayout = built;
+    renderer.resize(400, 201, 1);
+    await renderer.screenshot();
+    expect(built - beforeLayout).toBeLessThanOrEqual(1);
+    renderer.resize(400, 200, 1);
+    expect(await renderer.screenshot()).toBe(first);
+
+    for (let i = 0; i < 40; i++) renderer.scroll(0, 250);
+    expect(alive).toBeGreaterThan(0);
+    expect(alive).toBeLessThanOrEqual(256);
+    renderer.resize(400, 200, 2);
+    const zoomed = await renderer.screenshot();
+    expect((await new Bun.Image(Buffer.from(zoomed, "base64")).metadata()).width).toBe(800);
+    await renderer.loadDocument({ url: "https://paint.test/empty", status: 200, contentType: "text/html", source: "<!doctype html><body></body>" });
+    await renderer.whenLoaded();
+    expect(alive).toBe(0);
+  } finally {
+    renderer?.dispose();
+    CanvasKit.ParagraphBuilder.MakeFromFontCollection = original;
+  }
+  expect(alive).toBe(0);
+});
+
+test("screenshot encoding options are honored and separated in the frame cache", async () => {
+  const { CanvasKit: kit } = await loadGraphics();
+  const renderer = await createPageRenderer({});
+  const images = [];
+  try {
+    renderer.resize(400, 200, 1);
+    await renderer.loadDocument({ url: "https://capture.test/", contentType: "text/html",
+      source: "<body style='margin:0;color:#256;background:#def'><h1>Frame format cache</h1><p>Lossless PNG and JPEG capture</p>" });
+    await renderer.whenLoaded();
+    const png = await renderer.screenshot();
+    const jpeg = await renderer.screenshot({ format: "jpeg", quality: 85 });
+    expect((await new Bun.Image(Buffer.from(jpeg, "base64")).metadata()).format).toBe("jpeg");
+    const fast = await renderer.screenshot({ optimizeForSpeed: true });
+    const pixelBytes = value => {
+      const image = kit.MakeImageFromEncoded(Buffer.from(value, "base64"));
+      images.push(image);
+      return image.readPixels(0, 0, { width: 400, height: 200, colorType: kit.ColorType.RGBA_8888,
+        alphaType: kit.AlphaType.Unpremul, colorSpace: kit.ColorSpace.SRGB });
+    };
+    expect(pixelBytes(fast)).toEqual(pixelBytes(png));
+    expect(await renderer.screenshot()).toBe(png);
+  } finally {
+    for (const image of images) image.delete();
+    renderer.dispose();
+  }
+});

package/test/position-audio.test.js

@@ -65,3 +65,27 @@ test("an ended prefix or failed reopen never claims to have reached the target",
   const sound = track(pipe, 2);
   expect(await advanceAudio(() => sound, 8, { needsMore: () => false, reopen: async () => false })).toBe(false);
 });
+
+test("a seek before the first audio epoch cannot keep reopening an unreachable prefix", async () => {
+  let sound = { position: 6, decoder: { sampleRate: 1, channels: 1 } }, reopened = 0;
+  expect(await advanceAudio(() => sound, 2, {
+    needsMore: () => true,
+    reopen: async () => { reopened++; sound = { ...sound, position: 6 }; return true; },
+  })).toBe(false);
+  expect(reopened).toBe(1);
+});
+
+test("audio epoch EOF resumes at the next absolute sample cursor", async () => {
+  const pipe = createBytePipe(); pipe.finish();
+  let sound = { position: 6, pending: null, endTime: 6, snapshotId: 1, openedGeneration: 1, pipe,
+    decoder: { sampleRate: 1, channels: 1, nextSamples: () => null } };
+  expect(await advanceAudio(() => sound, 7, {
+    needsMore: () => true,
+    reopen: async () => {
+      sound = { ...sound, position: 6, endTime: Infinity, snapshotId: 2, pending: new Float32Array([6, 7]) };
+      return true;
+    },
+  })).toBe(true);
+  expect(sound.position).toBe(7);
+  expect([...sound.pending]).toEqual([7]);
+});