https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/
fix(render): make the manifest's `complete` flag mean something (#141)
Roberto Ringolic4b11254b981
diff --git a/plugin/commands/screenshot.md b/plugin/commands/screenshot.mdindex d21bd1f..314a1b7 100644--- a/plugin/commands/screenshot.md+++ b/plugin/commands/screenshot.md@@ -5,7 +5,7 @@ allowed-tools: "Bash, Read"---1. Run: `pixelshot $ARGUMENTS --output /tmp/pixelbrowse --tile-height 1568`-2. The output tile is at `/tmp/pixelbrowse/<domain>.png.tiles/tile_0000.jpg` — read it directly with the Read tool. Do not ls.+2. Read `/tmp/pixelbrowse/<domain>.png.tiles/tiles.json`, then read every tile it lists with the Read tool (they are `tile_NNNN.jpg` in that same directory, top of the page first). If the manifest says `"complete": false`, the page was only partly captured — report that alongside what you saw.3. If text is too small to read, crop with Pillow (always available — it's a pixelshot dependency):`python3 -c "from PIL import Image; Image.open('<tile>').crop((x1,y1,x2,y2)).save('/tmp/pixelbrowse/crop.png')"`4. Report what you see.diff --git a/plugin/skills/pixelbrowse/SKILL.md b/plugin/skills/pixelbrowse/SKILL.mdindex d5ef4cc..34ba8a2 100644--- a/plugin/skills/pixelbrowse/SKILL.md+++ b/plugin/skills/pixelbrowse/SKILL.md@@ -36,6 +36,8 @@ pixelshot document.pdf --output /tmp/pixelbrowseIMPORTANT: Always use `--tile-height 1568` for screenshots you will read visually.Claude's vision model downscales images with long edge > 1568px (Sonnet/Haiku) or 2576px (Opus).The default 8192px tile height will be downscaled and text becomes unreadable.+Note that the tile height is also the emulated viewport height, so at 1568 an ordinary article+is a dozen-plus tiles rather than one or two — the manifest tells you how many (see Workflow).IMPORTANT: Always use `--wait-network-idle` for URLs. Without it, JavaScript-heavypages (most modern sites / single-page apps) are captured before they finish rendering@@ -47,14 +49,27 @@ After rendering, read the tile images from the output directory to visually unde## Workflow1. Run `pixelshot <url> --output /tmp/pixelbrowse --tile-height 1568 --wait-network-idle`-2. Read `/tmp/pixelbrowse/<domain>.png.tiles/tile_0000.jpg` directly (no need to ls — the naming is deterministic)-3. If the page is long, also read tile_0001.jpg, tile_0002.jpg, etc.+2. Read `/tmp/pixelbrowse/<domain>.png.tiles/tiles.json` — the manifest of what was captured+3. Read every tile it lists, in order, not just `tile_0000.jpg`Output path pattern: `/tmp/pixelbrowse/<sanitized-url>.png.tiles/tile_NNNN.jpg`- For `https://news.ycombinator.com` → `/tmp/pixelbrowse/news.ycombinator.com.png.tiles/tile_0000.jpg`- For `https://example.com/page` → `/tmp/pixelbrowse/example.com_page.png.tiles/tile_0000.jpg`-Do NOT run `ls` — just read tile_0000.jpg. If it doesn't exist, the page had no content.+Read `tiles.json` rather than `ls` (or guessing at tile numbers) — it is one file read and it+answers both questions the tile files can't:++```json+{"url": "...", "page_height": 29184, "tile_height": 1568, "tiles": ["tile_0000.jpg", "..."], "complete": true}+```++- **`tiles`** — the full list. A long page is many tiles; reading only `tile_0000.jpg` on a+ 30,000px article means reading 5% of it. Read them all before summarising.+- **`complete: false`** — the capture is not trustworthy: pixelshot could not measure the page,+ so what you have is roughly one viewport of an unknown-length page. Say so in your answer+ rather than presenting it as the whole page. Re-running with `--wait-network-idle` (if it was+ omitted) or a different `--viewport-width` often fixes it.+- **No `tiles.json` at all** — the render failed. That is an error to report, not an empty page.## Crop & Zoomdiff --git a/render/src/pixelrag_render/backends/cdp.py b/render/src/pixelrag_render/backends/cdp.pyindex 948717e..434285e 100644--- a/render/src/pixelrag_render/backends/cdp.py+++ b/render/src/pixelrag_render/backends/cdp.py@@ -35,7 +35,7 @@ from pathlib import Pathfrom PIL import Image-from .page_metrics import CONTENT_BOTTOM_JS+from .page_metrics import CONTENT_BOTTOM_JS, truncation_reasonlogger = logging.getLogger("pixelrag_render.backends.cdp")@@ -444,8 +444,13 @@ async def capture_url(},)try:- page_height = result["result"]["value"]- except (KeyError, TypeError):+ page_height = int(result["result"]["value"])+ except (KeyError, TypeError, ValueError):+ page_height = 0+ # A zero/negative height is as much a probe failure as a missing one, and+ # would otherwise tile nothing at all while still claiming success.+ height_measured = page_height > 0+ if not height_measured:page_height = tile_htiles = []@@ -507,11 +512,24 @@ async def capture_url(idx += 1y += tile_h+ reason = truncation_reason(page_height, tile_h, measured=height_measured)+ if reason:+ logger.warning(+ "%s: %s — capturing what is on screen and marking the manifest incomplete",+ url,+ reason,+ )+manifest = {"url": url,"page_height": page_height,+ # The geometry the capture ran at. Recorded so a consumer reading+ # tiles.json later can redo the page_height/tile_height comparison+ # itself instead of being told the tile height out of band.+ "tile_height": tile_h,+ "viewport_width": viewport_w,"tiles": tiles,- "complete": True,+ "complete": reason is None,}with open(tile_dir / "tiles.json", "w") as f:json.dump(manifest, f)diff --git a/render/src/pixelrag_render/backends/fast_cdp.py b/render/src/pixelrag_render/backends/fast_cdp.pyindex d2e2f2c..a4a92bf 100644--- a/render/src/pixelrag_render/backends/fast_cdp.py+++ b/render/src/pixelrag_render/backends/fast_cdp.py@@ -34,7 +34,7 @@ import timeimport urllib.requestfrom pathlib import Path-from .page_metrics import CONTENT_BOTTOM_JS+from .page_metrics import CONTENT_BOTTOM_JS, truncation_reasonlogger = logging.getLogger("pixelrag_render.backends.fast_cdp")@@ -492,9 +492,11 @@ async def _run_render(},)page_h = r["result"]["result"]["value"]- if not page_h or page_h <= 0:+ height_measured = bool(page_h) and page_h > 0+ if not height_measured:page_h = tile_heightexcept Exception:+ height_measured = Falsepage_h = tile_heightn_tiles = max(1, (page_h + tile_height - 1) // tile_height)@@ -586,13 +588,29 @@ async def _run_render(n_written += 1tile_names.append(f"tile_{t:04d}.jpg")- # Write manifest+ # Write manifest. `complete` has to mean something here too —+ # see page_metrics.truncation_reason; the standard path applies+ # the identical rule, so a manifest reads the same whichever+ # Chrome the capture happened to run on.+ reason = truncation_reason(+ page_h, tile_height, measured=height_measured+ )+ if reason:+ logger.warning(+ "[w%d] %s: %s — marking the manifest incomplete",+ wi,+ art_path,+ reason,+ )+manifest = {"path": art_path,"url": target_url,"page_height": page_h,+ "tile_height": tile_height,+ "viewport_width": VIEWPORT_WIDTH,"tiles": tile_names,- "complete": True,+ "complete": reason is None,}with open(tile_dir / "tiles.json", "w") as f:json.dump(manifest, f)diff --git a/render/src/pixelrag_render/backends/page_metrics.py b/render/src/pixelrag_render/backends/page_metrics.pyindex 1800e95..bc1a5a7 100644--- a/render/src/pixelrag_render/backends/page_metrics.py+++ b/render/src/pixelrag_render/backends/page_metrics.py@@ -1,12 +1,14 @@-"""Shared in-page measurement JS for the capture backends.+"""Shared page measurement for the capture backends: the in-page JS, and the+judgement about whether what it measured can be trusted.Kept in one place because both backends measure page height the same way andmust agree: the standard (``cdp``) and turbo (``fast_cdp``) paths each embedthis snippet, and a divergence between them silently changes how much of a page-gets captured depending on which Chrome binary is installed.+gets captured depending on which Chrome binary is installed. The same goes for+what they then report in ``tiles.json``.-No imports — a plain string constant, so either backend can use it without a-dependency edge between them.+No imports — a plain string constant and a pure function, so either backend can+use them without a dependency edge between them."""# How tall is the document's *content*?@@ -42,3 +44,37 @@ CONTENT_BOTTOM_JS = """return Math.ceil(bottom + offset);}"""+++def truncation_reason(+ page_height: int, tile_height: int, *, measured: bool+) -> str | None:+ """Why this capture must not be reported as complete — or ``None`` if it may.++ ``tile_height`` is also the emulated viewport height (both backends pass it+ to ``Emulation.setDeviceMetricsOverride``), which is what makes the two+ checks below meaningful:++ - The probe returned nothing usable, so the height fell back to the tile+ height. Whatever the page actually was, one viewport of it was captured.+ - The probe returned exactly the viewport height. Then it measured the+ viewport rather than the content, and everything below the fold is+ missing — the shape every truncation so far has taken (issues #124, #131,+ #133), independent of which of them caused it.++ The second check costs a false alarm on a page that happens to be exactly+ ``tile_height`` tall. That is the right trade against the alternative,+ which is reporting 5% of an article as the whole of it: a capture wrongly+ flagged is re-run, a truncation never flagged is read and summarised.+ """+ if not measured:+ return (+ f"the page-height probe returned nothing, so the height fell back "+ f"to the {tile_height}px tile height"+ )+ if page_height == tile_height:+ return (+ f"the measured page height ({page_height}px) is exactly the tile "+ f"height, so the probe tracked the emulated viewport, not the content"+ )+ return Nonediff --git a/tests/test_render.py b/tests/test_render.pyindex b8a7a5b..46aec81 100644--- a/tests/test_render.py+++ b/tests/test_render.py@@ -17,6 +17,7 @@ from pathlib import Pathimport pytestfrom pixelrag_render import render_file+from pixelrag_render.backends.page_metrics import truncation_reasondef test_render_local_html_to_tiles(tmp_path):@@ -156,3 +157,62 @@ def test_hanging_web_font_does_not_stall_render(tmp_path):manifest = json.loads(manifests[0].read_text())assert manifest["page_height"] > 300assert len(manifest["tiles"]) > 1+++def test_manifest_records_the_geometry_the_capture_ran_at(tmp_path):+ """A consumer of tiles.json must be able to check the capture itself.++ ``page_height`` alone says nothing: it is only suspicious relative to the+ tile height, which used to be absent from URL manifests entirely, leaving a+ downstream reader guessing which ``--tile-height`` the capture used.+ """+ body = "".join(f"<p>line {i:03d}</p>" for i in range(400))+ html = tmp_path / "long.html"+ html.write_text(f"<!DOCTYPE html><html><body>{body}</body></html>")++ dirs = render_file(html, tmp_path / "tiles", tile_height=1000, viewport_width=1280)+ manifest = json.loads((Path(dirs[0]) / "tiles.json").read_text())++ assert manifest["tile_height"] == 1000+ assert manifest["viewport_width"] == 1280+ assert manifest["complete"] is True, (+ "a page measured well past its viewport is a healthy capture and must "+ f"not be flagged: {manifest}"+ )+++def test_capture_stuck_at_the_viewport_height_is_reported_incomplete(tmp_path):+ """The one page height that cannot be trusted must not claim completeness.++ A measured height exactly equal to the tile height (= the emulated viewport)+ is the signature of every truncation so far: the probe tracked the viewport+ instead of the content. The capture still runs — the tile written is real —+ but the manifest has to say the page may not be all there, because nothing+ else downstream can tell.+ """+ html = tmp_path / "one_viewport.html"+ html.write_text(+ '<!DOCTYPE html><html><body style="margin:0">'+ '<div style="height:1000px">content</div></body></html>'+ )++ dirs = render_file(html, tmp_path / "tiles", tile_height=1000, viewport_width=1280)+ tile_dir = Path(dirs[0])+ manifest = json.loads((tile_dir / "tiles.json").read_text())++ assert manifest["page_height"] == manifest["tile_height"] == 1000, (+ f"test setup no longer produces a viewport-height page: {manifest}"+ )+ assert manifest["complete"] is False+ assert sorted(tile_dir.glob("tile_*.jpg")), "the tile itself is still written"+++def test_truncation_reason_rules():+ # Healthy: measured, and not pinned to the viewport.+ assert truncation_reason(29184, 1568, measured=True) is None++ # Probe failed — the height is the tile height by fallback, not by measurement.+ assert "fell back" in truncation_reason(1568, 1568, measured=False)++ # Measured, but exactly one viewport: the truncation signature.+ assert "exactly the tile height" in truncation_reason(1568, 1568, measured=True)