From a6bdc4be0c74758249a90d3feb4faae55a990440 Mon Sep 17 00:00:00 2001 From: heznpc Date: Wed, 10 Jun 2026 15:57:25 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20xvfb=20claims=20match=20CI=20evidence?= =?UTF-8?q?=20=E2=80=94=20headed-under-xvfb=20unsupported,=20run=20headles?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 24-bit-xvfb suggestion implied a verified fix; in CI it failed silently. State the evidence instead: 8-bit breaks Page.captureScreenshot, 24-bit still failed — use headless in CI (the starter's capture.yml is now headless-only). --- AGENTS.md | 6 +++--- README.ko.md | 2 +- README.md | 4 ++-- skills/capture/SKILL.md | 5 ++--- src/launch.js | 4 ++-- 5 files changed, 10 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 00edeb4..6a27712 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,9 +49,9 @@ test/ → unit tests for the pure/safe modules (no browser) strips the extension subsystem; never switch to it. Under the full channel, headless **works** (`HEADED=0`; verified 2026-06-10 on macOS + Linux CI, recordVideo included); the local default stays headed for debuggability. - Headed-under-xvfb needs a 24-bit screen - (`xvfb-run -a --server-args="-screen 0 1920x1080x24"` — the 8-bit default - breaks `Page.captureScreenshot`). + Headed-under-xvfb is unsupported on CI runners (the 8-bit default breaks + `Page.captureScreenshot`; a 24-bit screen still failed silently) — run + headless in CI. - **Caption band stacks UNDER the shot** (scene captured at `height - bandHeight`, band appended) so the final image is the exact preset size and no UI is hidden. - **`promo.js` innerHTML** is trusted, build-time content only (the repo's own diff --git a/README.ko.md b/README.ko.md index dd44baa..e12fe56 100644 --- a/README.ko.md +++ b/README.ko.md @@ -38,7 +38,7 @@ npx playwright install chromium # 최초 1회: shotkit이 구동할 브라우 npx @starter-series/shotkit ``` -> shotkit은 **풀 Chromium**(`channel: 'chromium'`)을 구동합니다 — 확장 서브시스템이 없는 headless-shell이 아닙니다. **headless 동작 검증 완료**(`HEADED=0`; macOS·Linux CI, 영상 포함)이며 starter capture 워크플로의 기본값입니다. 로컬 기본은 디버깅 편의상 headed. CI에서 headed가 필요하면 xvfb에 24비트 화면을 주십시오(`--server-args="-screen 0 1920x1080x24"` — 8비트 기본값은 스크린샷 캡처가 깨집니다). +> shotkit은 **풀 Chromium**(`channel: 'chromium'`)을 구동합니다 — 확장 서브시스템이 없는 headless-shell이 아닙니다. **headless 동작 검증 완료**(`HEADED=0`; macOS·Linux CI, 영상 포함)이며 starter capture 워크플로의 기본값입니다. 로컬 기본은 디버깅 편의상 headed. CI 러너에서 headed-under-xvfb는 신뢰할 수 없었습니다(8비트 기본값은 스크린샷 캡처가 깨지고, 24비트로도 무성 실패) — CI에서는 headless를 쓰십시오. ## 사용 diff --git a/README.md b/README.md index ac61e9b..be998ee 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Zero-install in any repo that has a config: npx @starter-series/shotkit ``` -> shotkit launches the **full Chromium** (`channel: 'chromium'`) — never the default headless-shell, which strips the extension subsystem. **Headless works** (`HEADED=0`; verified on macOS and Linux CI, video included) and is the CI default in the starter's capture workflow; the local default stays headed for easy debugging. If you need headed-under-xvfb in CI, give xvfb a 24-bit screen (`xvfb-run -a --server-args="-screen 0 1920x1080x24"`) — the 8-bit default breaks Chromium's screenshot capture. +> shotkit launches the **full Chromium** (`channel: 'chromium'`) — never the default headless-shell, which strips the extension subsystem. **Headless works** (`HEADED=0`; verified on macOS and Linux CI, video included) and is the CI default in the starter's capture workflow; the local default stays headed for easy debugging. Headed-under-xvfb proved unreliable on CI runners (the 8-bit default breaks Chromium's screenshot capture, and a 24-bit screen still failed silently) — run headless in CI. ## Usage @@ -121,7 +121,7 @@ module.exports = { | Claude Code skill ([`skills/capture/`](skills/capture/SKILL.md)) | ✅ now | Claude Code (portable to Codex/Cursor/Gemini via the Agent Skills format) | | `AGENTS.md` run-block | ✅ now | every agent that reads AGENTS.md | | npm package (`@starter-series/shotkit`) | ✅ now | `npx` zero-install | -| Capture-in-CI GitHub Action | ✅ now — ships in [`browser-extension-starter`](https://github.com/starter-series/browser-extension-starter)'s `capture.yml` (headless default, 24-bit-xvfb fallback) | zero-local-browser runs + CI smoke test | +| Capture-in-CI GitHub Action | ✅ now — ships in [`browser-extension-starter`](https://github.com/starter-series/browser-extension-starter)'s `capture.yml` (headless) | zero-local-browser runs + CI smoke test | | `starter-series` marketplace entry | planned | discovery | | Video editing (`webm→mp4`, trim, captions) | planned | SNS clips | diff --git a/skills/capture/SKILL.md b/skills/capture/SKILL.md index a1fde75..637ae5c 100644 --- a/skills/capture/SKILL.md +++ b/skills/capture/SKILL.md @@ -35,8 +35,7 @@ rendered from the shipped code. ## Notes - Runs the full-Chromium channel; headless works (`HEADED=0 npx …` — verified, - video included) and is the right mode for CI. If headed-in-CI is required, - use `xvfb-run -a --server-args="-screen 0 1920x1080x24"` (the 8-bit xvfb - default breaks Chromium screenshots). + video included) and is the mode to use in CI. Headed-under-xvfb is + unreliable on CI runners — don't use it. - Scenes are the repo's own config — to change *what* is captured, edit `shotkit.config.js`, not shotkit. diff --git a/src/launch.js b/src/launch.js index 7a560b3..8fd61d3 100644 --- a/src/launch.js +++ b/src/launch.js @@ -10,8 +10,8 @@ * (no service worker, MV3 onInstalled never fires) — the full Chromium * channel is required. Under it, headless ALSO works (HEADED=0; verified * 2026-06-10 on macOS + Linux CI, recordVideo included). The local - * default stays headed for easy debugging. Headed-under-xvfb needs a - * 24-bit screen (--server-args="-screen 0 1920x1080x24"). + * default stays headed for easy debugging. Headed-under-xvfb proved + * unreliable on CI runners — prefer headless there. * * --disable-features=DisableLoadExtensionCommandLineSwitch * Chromium 121+ guards --load-extension behind this flag by default.