mirror of
https://github.com/garrytan/gstack.git
synced 2026-07-10 01:48:38 +02:00
docs(browse): offline render mode + canonical-Chromium guidance
Document the blessed offline-render path (headless, no proxy/Xvfb): visual output via screenshot --selector, bytes a function returns via js --out. Add the puppeteer->browse cheatsheet row, a "don't bundle your own Chromium" note (browse skill + CONTRIBUTING), and the --out/--raw command descriptions. Regenerate browse/SKILL.md, SKILL.md, and gstack/llms.txt from the templates.
This commit is contained in:
@@ -135,6 +135,51 @@ $B screenshot /tmp/out.png --selector .tweet-card
|
||||
```
|
||||
Scale must be 1-3 (gstack policy cap). Changing `--scale` recreates the browser context; refs from `snapshot` are invalidated (rerun `snapshot`), but `load-html` content is replayed automatically. Not supported in headed mode.
|
||||
|
||||
### 14. Offline render mode (rasterize your own HTML/JSON, zero network)
|
||||
|
||||
This is the blessed path for "I just want to turn my own local HTML or JSON into a
|
||||
PNG/PDF/bytes on disk" — Excalidraw diagrams, tweet/quote cards, og-images,
|
||||
report rasterization. It is **plain headless, shared Chromium, no proxy, no Xvfb,
|
||||
no anti-bot stealth**. Default `$B` is already exactly this; you do not pass
|
||||
`--headed` or `--proxy`. One Chromium per box, shared by every skill — **do not
|
||||
`npm i puppeteer` and ship a second browser** (see the note under the cheatsheet).
|
||||
|
||||
Two output shapes, pick by what you have:
|
||||
|
||||
**A) Visual output → `screenshot --selector` (preferred).** If the thing you want
|
||||
is a picture of something on the page, screenshot it. The PNG is written from the
|
||||
browser process straight to disk — the image bytes never cross the CDP wire.
|
||||
|
||||
```bash
|
||||
echo '<div id="card" style="width:400px;height:200px;background:#1da1f2;color:#fff;padding:20px">hi</div>' > /tmp/card.html
|
||||
$B viewport 480x600 --scale 2
|
||||
$B load-html /tmp/card.html
|
||||
$B screenshot /tmp/card.png --selector '#card' # disk path — no megabytes over CDP
|
||||
```
|
||||
(Use the disk path, NOT `screenshot --base64` — base64 serializes the bytes back
|
||||
through the command channel, which is the cost you're trying to avoid.)
|
||||
|
||||
**B) Bytes a function returns → `js --out` / `eval --out`.** When a library hands
|
||||
you the result as a return value (a base64 data URL, a blob, computed JSON) rather
|
||||
than painting a stable element — e.g. Excalidraw's export function returns a PNG
|
||||
data URL — write the evaluate result straight to disk. `--out` decodes a
|
||||
`data:*;base64,...` result to raw bytes automatically (pass `--raw` to write the
|
||||
literal string). The payload is written by the daemon and never serialized back
|
||||
out to the CLI/stdout.
|
||||
|
||||
```bash
|
||||
# Load the render bundle, signal readiness, then render-to-file.
|
||||
$B load-html /tmp/excalidraw-export.html # bundle sets window.__render + a #done flag
|
||||
$B wait '#done' # deterministic ready handshake
|
||||
$B js "window.__render(SCENE_JSON)" --out /tmp/diagram.png # data URL → decoded PNG on disk
|
||||
```
|
||||
|
||||
`--out` is a WRITE: it needs the `write` scope and is never allowed over the
|
||||
pair-agent tunnel (a remote agent can't write to your disk). Parent directories
|
||||
are created; malformed base64 errors instead of writing corrupt bytes. Pick A when
|
||||
you can (no CDP transfer at all); reach for B only when the bytes come back as a
|
||||
return value.
|
||||
|
||||
## Puppeteer → browse cheatsheet
|
||||
|
||||
Migrating from Puppeteer? Here's the 1:1 mapping for the core workflow:
|
||||
@@ -148,6 +193,8 @@ Migrating from Puppeteer? Here's the 1:1 mapping for the core workflow:
|
||||
| `await (await page.$('.x')).screenshot({path})` | `$B screenshot <path> --selector .x` |
|
||||
| `await page.screenshot({fullPage: true, path})` | `$B screenshot <path>` (full page default) |
|
||||
| `await page.screenshot({clip: {x, y, w, h}, path})` | `$B screenshot <path> --clip x,y,w,h` |
|
||||
| `const r = await page.evaluate(fn)` | `$B js "<expr>"` (result to stdout) |
|
||||
| `fs.writeFileSync(out, Buffer.from(dataUrl.split(',')[1],'base64'))` | `$B js "<expr>" --out <file>` (data URL auto-decoded) |
|
||||
|
||||
Worked example (the tweet-renderer flow — Puppeteer → browse):
|
||||
|
||||
@@ -162,6 +209,13 @@ $B screenshot /tmp/out.png --selector .tweet-card
|
||||
|
||||
Aliases: typing `setcontent` or `set-content` routes to `load-html` automatically. Typing a typo (`load-htm`) returns `Did you mean 'load-html'?`.
|
||||
|
||||
**Don't bundle your own puppeteer/Chromium.** `browse` is the one shared Chromium
|
||||
per box. Skills that need to rasterize local HTML/JSON (diagrams, cards, og-images)
|
||||
should route through `browse` — `screenshot --selector` for visual output,
|
||||
`load-html` + `js --out` for bytes a function returns — instead of
|
||||
`npm i puppeteer` and downloading a second Chromium that drifts out of version sync.
|
||||
One install to pin, one daemon's lifecycle to manage.
|
||||
|
||||
## User Handoff
|
||||
|
||||
When you hit something you can't handle in headless mode (CAPTCHA, complex auth, multi-factor
|
||||
|
||||
Reference in New Issue
Block a user