Skip to content

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.md
index 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.md
index d5ef4cc..34ba8a2 100644
--- a/plugin/skills/pixelbrowse/SKILL.md
+++ b/plugin/skills/pixelbrowse/SKILL.md
@@ -36,6 +36,8 @@ pixelshot document.pdf --output /tmp/pixelbrowse
IMPORTANT: 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-heavy
pages (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
## Workflow
1. 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 & Zoom
diff --git a/render/src/pixelrag_render/backends/cdp.py b/render/src/pixelrag_render/backends/cdp.py
index 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 Path
from PIL import Image
-from .page_metrics import CONTENT_BOTTOM_JS
+from .page_metrics import CONTENT_BOTTOM_JS, truncation_reason
logger = 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_h
tiles = []
@@ -507,11 +512,24 @@ async def capture_url(
idx += 1
y += 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.py
index 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 time
import urllib.request
from pathlib import Path
-from .page_metrics import CONTENT_BOTTOM_JS
+from .page_metrics import CONTENT_BOTTOM_JS, truncation_reason
logger = 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_height
except Exception:
+ height_measured = False
page_h = tile_height
n_tiles = max(1, (page_h + tile_height - 1) // tile_height)
@@ -586,13 +588,29 @@ async def _run_render(
n_written += 1
tile_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.py
index 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 and
must agree: the standard (``cdp``) and turbo (``fast_cdp``) paths each embed
this 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 None
diff --git a/tests/test_render.py b/tests/test_render.py
index b8a7a5b..46aec81 100644
--- a/tests/test_render.py
+++ b/tests/test_render.py
@@ -17,6 +17,7 @@ from pathlib import Path
import pytest
from pixelrag_render import render_file
+from pixelrag_render.backends.page_metrics import truncation_reason
def 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"] > 300
assert 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)