@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/presets/code-vibe/skills/record-browser-gif/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: record-browser-gif
+description: 浏览器演示录制/GIF 证据；Record browser/Web UI interaction demos as optimized GIFs via the browser-control workflow or Playwright Videos, with deterministic encoding, then attach to a pull request with `gh --attach`, falling back to an assets branch. Use when asked to make/record/generate a GIF of a browser workflow, and for every PR changing user-visible GUI behavior, which MUST include a GIF from the PR's real server and model flow.
+
+<!-- provenance: ported from deepseek-ai/deepseek-harness/.agents/skills/record-browser-gif @ 00102833dfaee1da9f48a3a8eae9d34005a75218 (MIT License, Copyright (c) 2026 DeepSeek). Content adapted for self-contained operation outside the upstream repo. -->
+---
+
+# Record Browser GIF
+
+Produce a short, truthful UI demonstration as a local GIF, and — only when the task includes attaching it to a pull request — publish it through the attach workflow at the end of this skill. The available browser-control workflow remains preferred. Use [Playwright Videos](https://playwright.dev/docs/videos) when that workflow supports continuous capture at higher frame rates; use the bundled encoder for trimming, playback speed, final hold, dimensions, and size.
+
+The evidence-chain decision（上游决策档案，源自 DeepSeek Harness）owns why one storyboard comes from one isolated run and why publication revalidates both the artifact and the demonstrated pull-request head.
+
+## Every GUI pull request includes a GIF
+
+A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via [the attach workflow](#publish-the-gif).
+
+The recording itself is part of the evidence: use a real server booted from that pull request's branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for a fixture recording. Next to the embed, state the exact demonstrated commit SHA, the tree and origin that served it, any mode flags or browser-state exceptions, and whether a real model round ran, so reviewers know exactly what the recording proves.
+
+## Keep recording separate from publication
+
+- Recording produces local video or screenshots and one `.gif` artifact only; it never mutates remote state.
+- Publication — attaching the GIF to a pull request body with `gh --attach`, or pushing it to an assets branch and embedding its URL where attach cannot apply — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch.
+- Preserve the requested recording conditions. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
+- Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.
+
+## Stage the application
+
+A GIF for a specific pull request demonstrates that pull request's tree, so stage per pull request:
+
+1. Require a clean worktree, record its exact commit with `git rev-parse HEAD`, then build that recorded tree — here, 按被测项目自身的构建命令执行（本环境以 package.json 的 build 脚本为准，替代上游的 pnpm run build:web）。A GIF recorded against another commit's build misattributes the evidence.
+2. Boot one server per port from that tree with fresh scratch `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state. Give the browser a fresh isolated context or profile as well; if the browser workflow cannot create one, clear that origin's cookies and site storage before navigation so persisted client state cannot affect the evidence. Source the root `.env` for the API key through the application's normal path; never echo the key.
+3. Treat one storyboard as one evidence run: every published frame comes from that server and those state roots, workspace, session, and model-backed scenario run. If capture automation fails, discard its frames and rerun from fresh roots; never splice frames from separate runs.
+4. When switching between pull requests, stop the old server by PID or an exact match on its command line. A broad `pkill -f` pattern can match and kill the shell that launched it — including your own.
+
+## Record the flow
+
+Follow the available browser-control workflow's setup, interaction, and cleanup instructions. When it exposes `recordVideo`, enable video on the same controlled context to capture more intermediate frames. Otherwise use [screenshot capture](#screenshot-capture) within that workflow; video availability does not determine which browser-control workflow to use. Existing user browser state remains an explicit isolation exception.
+
+Only when browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser and state that fallback in the capture notes. In this repository it resolves from `apps/web/package.json`; do not install another driver or open the user's browser.
+
+Before recording, identify the origin, built or development server, transport, and any mode overrides. When a production default opens a native surface that automation cannot drive, select an official browser-operable production backend through normal application configuration and disclose the override.
+
+Store the script, raw video, timing notes, QA frames, and GIF under the repository's gitignored `.playwright-mcp/` directory. Create the run directory first.
+
+### Capture video
+
+Match `viewport` and `recordVideo.size` explicitly: Playwright otherwise scales the video down to fit 800×800, which can make UI text unreadable.
+
+Configure video through the chosen browser-control workflow. The standalone Playwright fallback uses:
+
+```js
+const { chromium } = createRequire(join(repo, 'apps/web/package.json'))('playwright')
+const browser = await chromium.launch()
+const size = { width: 1440, height: 900 }
+const context = await browser.newContext({
+  viewport: size,
+  recordVideo: { dir: join(runDir, 'videos'), size },
+})
+try {
+  const page = await context.newPage()
+  const video = page.video()
+  // Navigate and exercise the real application here.
+  await context.close()
+  await video.saveAs(join(runDir, 'demo.webm'))
+} finally {
+  await context.close()
+  await browser.close()
+}
+```
+
+Import `createRequire` from `node:module` and `join` from `node:path`; set `repo` and a fresh `runDir` to absolute paths in the recording script. Retain the page's video handle before closing it. Await `context.close()` before `video.saveAs()` or encoding; closing only the browser does not guarantee the video's flush. Each page has its own video: choose the demonstrated page explicitly and do not concatenate unrelated pages or runs. Failed runs are diagnostic only.
+
+Choose a short story with three to six meaningful states. Wait for unique semantic locators before acting; use `exact: true` for accessible-name equality and exact-text completion predicates that cannot match a prompt echo. Fixed waits may provide a reading hold after the state is verified, but never establish readiness. When capturing video, preserve animations and scrolling.
+
+When demonstrating a tool call, rejection, or recovery, open its detail or trajectory so the video shows the tool identity, status or stable error code, and downstream result. If a transient running state matters, prompt for a slow foreground operation and observe its concrete DOM marker; continuous video captures its intermediate frames. Give the model a short final sentinel to anchor completion. Stop an unnecessarily long real-API run after the demonstrated state is visible.
+
+Capture no secrets, personal data, unrelated tabs, or notifications. Browser video contains page content, not browser chrome; avoid rendering credential-bearing URLs in the application. Review the whole selected interval, including intermediate states. Keep one viewport throughout.
+
+## Encode the GIF
+
+Require `python3`, `ffmpeg`, and `ffprobe`. If a media binary is missing, report the dependency instead of installing software without authorization. Export `GIF_SKILL_DIR` on its own line before using it; an inline assignment cannot affect argument expansion in the same command.
+
+```sh
+export GIF_SKILL_DIR=/absolute/path/to/this/skill
+python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
+  /absolute/path/to/demo.webm \
+  /absolute/path/to/demo.gif \
+  --start 2 --end 32 --speed 2 --final-hold 3 \
+  --fps 10 --max-width 1200 --colors 128
+```
+
+`--start` and `--end` select one continuous source interval in seconds. Defaults retain the full video at 1× speed and add a two-second final hold. `--speed` changes playback speed; disclose it and the selected interval beside the GIF so the demo cannot imply measured response latency. Use observed video times, not guessed wall-clock offsets, and preserve the complete cause and outcome of the demonstrated behavior. The final hold repeats the last selected frame. `--fps` sets the encoded GIF frame rate; increasing it cannot recover motion that the source recording did not capture. Keep the original WebM for QA; do not splice separate runs or synthesize missing states.
+
+The encoder probes WebM container duration, applies trim and speed before palette conversion, and checks encoded duration, animation, width, and byte size. It refuses an empty or out-of-range interval, a selection shorter than two output frames, mode-inappropriate flags, and accidental overwrite. Reduce `--max-width`, then `--colors` or `--fps` for a large artifact; preserve readable text. Use `--force` only after resolving the exact output path.
+
+### Screenshot capture
+
+When continuous video is unavailable or the user requests a storyboard, follow the available browser-control workflow. Capture three to six verified states from one isolated run with the browser's screenshot API. Save returned image bytes directly under one run directory as `00-initial.png`, `01-typed.png`, and so on; use identical dimensions and crop. For a transient state, poll its DOM marker and capture within the same browser-script call.
+
+```sh
+python3 "$GIF_SKILL_DIR/scripts/encode_gif.py" \
+  /absolute/path/to/frames /absolute/path/to/demo.gif \
+  --durations 1.5,1.5,1.5,3.5 --fps 10 --max-width 1200 --colors 128
+```
+
+One duration applies to every screenshot; otherwise supply one positive duration per frame and hold the settled state longest. Directory input rejects fewer than two frames and mismatched dimensions or duration counts. Video timing flags apply only to video files; `--durations` and `--pattern` apply only to screenshot directories.
+
+## Verify the artifact
+
+1. Read the encoder's JSON summary and confirm the output path, source interval and speed (or screenshot count), encoded frame count, dimensions, duration, and byte size.
+2. Visually read the encoded GIF itself, not only the source frames. Confirm that the transition is legible, the last state is held long enough, and no sensitive content appears. If the viewer renders only the first frame, decode representative frames from the encoded GIF with `ffmpeg` and inspect those; the pre-encode screenshots do not prove the encoded order, palette, or final hold.
+3. Run `git status --short` and confirm raw video, QA frames, and the artifact landed only under ignored paths.
+4. Return the absolute GIF path, render it when the client supports local media, and state whether the recording used a real API, fixture, or another transport. When the task does not include attaching the GIF to a pull request, stop here.
+
+Encoder maintenance: run `python3 -m unittest discover -s "$GIF_SKILL_DIR/scripts" -p 'test_*.py' -v` with the media prerequisites installed. These local media tests do not run in repository CI.
+
+## Publish the GIF
+
+Perform this step only when the task includes attaching the GIF to a pull request.
+
+Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. Prefer `gh --attach`, which uploads the GIF to GitHub and rewrites the body reference in one command, so no branch carries the media.
+
+### Attach with gh
+
+`gh --attach` requires `gh` v2.99.0 or later (`gh --version`), a repository on github.com — GitHub Enterprise Server is not supported — write access to the repository, and a GIF at or below 10 MB. Confirm the verified artifact fits that limit; when it does not, shrink it with `--max-width`, then `--colors` or `--fps`, before attaching.
+
+Write the GIF into the body file as an ordinary local-path reference, using the same path passed to `--attach`; `gh` rewrites the reference in place to the uploaded URL, keeping its position and alt text:
+
+```markdown
+![<alt text>](<path/to/demo.gif>)
+```
+
+The demonstrated pull request is normally the publication target. A tooling pull request may instead embed a clearly labeled example from another pull request; name that source PR and compare its live head in every check below. Never attribute the example to the tooling branch.
+
+Immediately before attaching, re-read the demonstrated pull request's live head — for a new demonstrated pull request, the pushed branch tip — and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. Then attach:
+
+```sh
+gh pr create --body-file <body.md> --attach <path/to/demo.gif>     # new pull request
+gh pr edit <pr> --body-file <body.md> --attach <path/to/demo.gif>  # existing pull request
+```
+
+`--attach` is repeatable but refuses the same file twice. A GIF the body does not reference is appended at the end, where alt text set on the flag (`--attach '<path>#<alt text>'`) applies; a rewritten reference keeps the body's alt text. After attaching, re-read the demonstrated live head and require it to remain at that recorded commit. Re-read the live body and confirm the reference now points at the uploaded URL, render the body through GitHub's Markdown API and confirm the expected `<img>`, and fetch the uploaded URL once to confirm `200` and `image/gif`.
+
+### Fall back to an assets branch
+
+Use the assets-branch workflow only when `gh --attach` cannot apply: the GIF still exceeds 10 MB, `gh` is older than v2.99.0, or the repository is not on github.com. GIFs then live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (named `<series>-assets`; list existing ones with `git ls-remote --heads origin '*assets*'`).
+
+Before either workflow below pushes, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact.
+
+For an existing assets branch, work in a shallow single-branch scratch clone so the publication cannot touch your working tree:
+
+```sh
+git clone --branch <assets-branch> --single-branch --depth 1 <repo-url> /tmp/assets-checkout
+cp /absolute/path/to/demo.gif /tmp/assets-checkout/<name>.gif
+cd /tmp/assets-checkout
+git add <name>.gif
+git commit -m "assets: <what it shows> gif (#<pr>)"
+git push origin <assets-branch>
+```
+
+For a new series, make a fresh shallow scratch clone (`git clone --depth 1 <repo-url> /tmp/assets-checkout`), create the orphan branch with `git switch --orphan <assets-branch>`, then add the GIF, commit, and push the same way.
+
+After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
+
+Immediately before editing the pull-request body, re-read the demonstrated pull request's live head and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. After the edit, re-read the demonstrated live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
+
+Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image:
+
+```markdown
+![<alt text>](https://github.com/<owner>/<repo>/blob/<assets-branch>/<name>.gif?raw=true)
+```
+
+Never delete or rewrite an assets branch, and never force-push it: merged pull request bodies reference its URLs forever. Append new commits only.

package/presets/code-vibe/skills/record-browser-gif/scripts/encode_gif.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""Encode a Playwright video or ordered browser screenshots into a verified GIF."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import NoReturn
+
+
+DEFAULT_MAX_BYTES = 5 * 1024 * 1024
+
+
+def fail(message: str) -> NoReturn:
+    """Exit with a concise user-correctable error."""
+    raise SystemExit(f"error: {message}")
+
+
+def positive_float(value: str) -> float:
+    """Parse one finite positive command-line number."""
+    try:
+        parsed = float(value)
+    except ValueError:
+        fail(f"expected a number, got {value!r}")
+    if not math.isfinite(parsed) or parsed <= 0:
+        fail(f"expected a positive finite number, got {value!r}")
+    return parsed
+
+
+def positive_int(value: str) -> int:
+    """Parse one positive command-line integer."""
+    try:
+        parsed = int(value)
+    except ValueError:
+        fail(f"expected an integer, got {value!r}")
+    if parsed <= 0:
+        fail(f"expected a positive integer, got {value!r}")
+    return parsed
+
+
+def nonnegative_float(value: str) -> float:
+    """Parse a finite nonnegative timestamp or hold duration."""
+    try:
+        parsed = float(value)
+    except ValueError:
+        fail(f"expected a number, got {value!r}")
+    if not math.isfinite(parsed) or parsed < 0:
+        fail(f"expected a nonnegative finite number, got {value!r}")
+    return parsed
+
+
+def parse_durations(value: str, frame_count: int) -> list[float]:
+    """Expand one hold duration or validate one duration per source frame."""
+    parts = [part.strip() for part in value.split(",")]
+    if not parts or any(not part for part in parts):
+        fail("--durations must be a number or a comma-separated list of numbers")
+    durations = [positive_float(part) for part in parts]
+    if len(durations) == 1:
+        return durations * frame_count
+    if len(durations) != frame_count:
+        fail(f"--durations supplied {len(durations)} values for {frame_count} frames")
+    return durations
+
+
+def require_binary(name: str) -> str:
+    """Resolve a required media binary or fail without attempting installation."""
+    path = shutil.which(name)
+    if path is None:
+        fail(f"required binary {name!r} is not available on PATH")
+    return path
+
+
+def run_json(command: list[str]) -> dict[str, object]:
+    """Run a media probe and parse its JSON object."""
+    try:
+        completed = subprocess.run(command, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as error:
+        detail = error.stderr.strip() or error.stdout.strip() or str(error)
+        fail(detail)
+    try:
+        value = json.loads(completed.stdout)
+    except json.JSONDecodeError as error:
+        fail(f"media probe returned invalid JSON: {error}")
+    if not isinstance(value, dict):
+        fail("media probe returned a non-object JSON value")
+    return value
+
+
+def probe_stream(ffprobe: str, path: Path) -> dict[str, object]:
+    """Read the first video stream's dimensions and timing metadata."""
+    result = run_json(
+        [
+            ffprobe,
+            "-v",
+            "error",
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "stream=width,height,nb_frames,duration,r_frame_rate",
+            "-of",
+            "json",
+            str(path),
+        ]
+    )
+    streams = result.get("streams")
+    if not isinstance(streams, list) or len(streams) != 1 or not isinstance(streams[0], dict):
+        fail(f"expected one video stream in {path}")
+    return streams[0]
+
+
+def video_duration(ffprobe: str, path: Path) -> float:
+    """Read container duration because Playwright WebM omits stream duration."""
+    result = run_json([
+        ffprobe, "-v", "error", "-show_entries", "format=duration", "-of", "json", str(path),
+    ])
+    metadata = result.get("format")
+    if not isinstance(metadata, dict):
+        fail(f"missing format metadata for {path}")
+    return positive_float(str(metadata.get("duration")))
+
+
+def stream_int(stream: dict[str, object], key: str, path: Path) -> int:
+    """Read a positive integer stream field."""
+    try:
+        value = int(stream[key])
+    except (KeyError, TypeError, ValueError):
+        fail(f"missing integer {key!r} in media probe for {path}")
+    if value <= 0:
+        fail(f"non-positive {key!r} in media probe for {path}")
+    return value
+
+
+def ffconcat_quote(path: Path) -> str:
+    """Quote an ffconcat path while preserving literal backslashes."""
+    value = str(path)
+    if "\n" in value or "\r" in value:
+        fail(f"frame path contains a newline: {path}")
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+def write_concat_manifest(path: Path, frames: list[Path], durations: list[float]) -> None:
+    """Write an ffconcat manifest that materializes the final frame's hold."""
+    lines = ["ffconcat version 1.0"]
+    for frame, duration in zip(frames, durations):
+        lines.append(f"file {ffconcat_quote(frame)}")
+        lines.append(f"duration {duration:.6f}")
+    lines.append(f"file {ffconcat_quote(frames[-1])}")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line contract."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path, help="video file or directory of ordered screenshots")
+    parser.add_argument("output", type=Path, help="output .gif path")
+    parser.add_argument("--pattern", help="screenshot glob (default: *.png; directory input only)")
+    parser.add_argument(
+        "--durations",
+        help="screenshot holds (default: 2 seconds each; directory input only)",
+    )
+    parser.add_argument("--start", type=nonnegative_float, help="video trim start in seconds (default: 0)")
+    parser.add_argument("--end", type=positive_float, help="video trim end in seconds (default: EOF)")
+    parser.add_argument("--speed", type=positive_float, help="video playback multiplier (default: 1)")
+    parser.add_argument("--final-hold", type=nonnegative_float, help="extra final video frame hold (default: 2 seconds)")
+    parser.add_argument("--fps", type=positive_int, default=10, help="encoded frames per second")
+    parser.add_argument(
+        "--max-width",
+        type=positive_int,
+        default=1200,
+        help="maximum output width",
+    )
+    parser.add_argument(
+        "--colors",
+        type=positive_int,
+        default=128,
+        help="palette colors, from 4 through 256",
+    )
+    parser.add_argument(
+        "--max-bytes",
+        type=positive_int,
+        default=DEFAULT_MAX_BYTES,
+        help="maximum output size",
+    )
+    parser.add_argument("--force", action="store_true", help="replace an existing output file")
+    return parser
+
+
+def main() -> None:
+    """Validate inputs, encode the GIF, verify it, and print a JSON summary."""
+    args = build_parser().parse_args()
+    source = args.input.resolve()
+    output = args.output.resolve()
+
+    if not source.exists():
+        fail(f"input does not exist: {source}")
+    is_video = source.is_file()
+    if not is_video and not source.is_dir():
+        fail(f"input must be a video file or frame directory: {source}")
+    if output.suffix.lower() != ".gif":
+        fail(f"output must end in .gif: {output}")
+    if output.exists() and not args.force:
+        fail(f"output already exists (pass --force to replace it): {output}")
+    if not 4 <= args.colors <= 256:
+        fail("--colors must be between 4 and 256")
+    if args.fps > 30:
+        fail("--fps must not exceed 30")
+
+    ffmpeg = require_binary("ffmpeg")
+    ffprobe = require_binary("ffprobe")
+    details: dict[str, object]
+    if is_video:
+        if args.pattern is not None or args.durations is not None:
+            fail("--pattern and --durations require a screenshot directory")
+        if source == output:
+            fail("output path must not match the input video")
+        probe_stream(ffprobe, source)
+        source_duration = video_duration(ffprobe, source)
+        start = args.start if args.start is not None else 0.0
+        end = args.end if args.end is not None else source_duration
+        speed = args.speed if args.speed is not None else 1.0
+        final_hold = args.final_hold if args.final_hold is not None else 2.0
+        if not start < end <= source_duration:
+            fail(f"video trim must satisfy 0 <= start < end <= {source_duration:.3f}")
+        if (end - start) / speed < 2 / args.fps:
+            fail("video selection must span at least two output frames before the final hold")
+        expected_duration = (end - start) / speed + final_hold
+        details = {
+            "sourceVideo": str(source), "sourceDurationSeconds": source_duration,
+            "startSeconds": start, "endSeconds": end, "speed": speed,
+            "finalHoldSeconds": final_hold,
+        }
+    else:
+        if any(value is not None for value in (args.start, args.end, args.speed, args.final_hold)):
+            fail("--start, --end, --speed and --final-hold require a video file")
+        pattern = args.pattern if args.pattern is not None else "*.png"
+        if not pattern:
+            fail("--pattern must not be empty")
+        frames = sorted(path.resolve() for path in source.glob(pattern) if path.is_file())
+        if len(frames) < 2:
+            fail(f"expected at least two frames in {source}")
+        if output in frames:
+            fail("output path must not match an input frame")
+        durations = parse_durations(args.durations if args.durations is not None else "2", len(frames))
+        expected_duration = sum(durations)
+        dimensions = {
+            (stream_int(stream, "width", frame), stream_int(stream, "height", frame))
+            for frame in frames
+            for stream in [probe_stream(ffprobe, frame)]
+        }
+        if len(dimensions) != 1:
+            fail(f"all frames must have identical dimensions, got {sorted(dimensions)}")
+        details = {"sourceFrames": len(frames)}
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="record-browser-gif-") as temporary:
+        if is_video:
+            inputs = ["-i", str(source)]
+            timing = f"trim=start={start}:end={end},setpts=(PTS-STARTPTS)/{speed},"
+            hold = f",tpad=stop_mode=clone:stop_duration={final_hold}"
+        else:
+            manifest = Path(temporary) / "frames.ffconcat"
+            write_concat_manifest(manifest, frames, durations)
+            inputs = ["-f", "concat", "-safe", "0", "-i", str(manifest)]
+            timing = ""
+            hold = ""
+        scale = f"scale='min({args.max_width},iw)':-2:flags=lanczos"
+        palette = f"palettegen=max_colors={args.colors}:stats_mode=full"
+        filters = (
+            f"{timing}fps={args.fps},{scale}{hold},split[base][palette_input];"
+            f"[palette_input]{palette}[palette];"
+            "[base][palette]paletteuse=dither=bayer:bayer_scale=3:diff_mode=rectangle"
+        )
+        command = [
+            ffmpeg,
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            *inputs,
+            "-vf",
+            filters,
+            "-loop",
+            "0",
+            "-t",
+            f"{expected_duration:.6f}",
+            "-y" if args.force else "-n",
+            str(output),
+        ]
+        try:
+            subprocess.run(command, check=True)
+        except subprocess.CalledProcessError as error:
+            fail(f"ffmpeg failed with exit code {error.returncode}")
+
+    stream = probe_stream(ffprobe, output)
+    width = stream_int(stream, "width", output)
+    height = stream_int(stream, "height", output)
+    encoded_frames = stream_int(stream, "nb_frames", output)
+    try:
+        actual_duration = float(stream["duration"])
+    except (KeyError, TypeError, ValueError):
+        fail(f"missing duration in media probe for {output}")
+    tolerance = max(0.2, 2 / args.fps)
+    if abs(actual_duration - expected_duration) > tolerance:
+        fail(f"expected about {expected_duration:.3f}s, encoded {actual_duration:.3f}s")
+    if width > args.max_width:
+        fail(f"expected width at most {args.max_width}, encoded {width}")
+    if encoded_frames < 2:
+        fail(f"expected an animated GIF, encoded {encoded_frames} frame")
+
+    byte_size = output.stat().st_size
+    if byte_size > args.max_bytes:
+        fail(f"output is {byte_size} bytes, above --max-bytes {args.max_bytes}")
+
+    print(
+        json.dumps(
+            {
+                "output": str(output),
+                **details,
+                "encodedFrames": encoded_frames,
+                "width": width,
+                "height": height,
+                "durationSeconds": actual_duration,
+                "fps": args.fps,
+                "bytes": byte_size,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

package/presets/code-vibe/skills/record-browser-gif/scripts/test_encode_gif.py

@@ -0,0 +1,103 @@
+"""Exercise GIF timing and rejection through real ffmpeg/ffprobe subprocesses."""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT = Path(__file__).with_name('encode_gif.py')
+
+
+class EncodeGifTest(unittest.TestCase):
+    def setUp(self):
+        self.temporary = tempfile.TemporaryDirectory(prefix='gif-encoder-test-')
+        self.addCleanup(self.temporary.cleanup)
+        self.root = Path(self.temporary.name)
+        self.video = self.root / 'browser video.webm'
+        self.output = self.root / 'demo.gif'
+        subprocess.run([
+            'ffmpeg', '-v', 'error',
+            '-f', 'lavfi', '-i', 'color=red:s=64x48:r=10:d=2',
+            '-f', 'lavfi', '-i', 'color=lime:s=64x48:r=10:d=2',
+            '-f', 'lavfi', '-i', 'color=blue:s=64x48:r=10:d=2',
+            '-filter_complex', '[0:v][1:v][2:v]concat=n=3:v=1:a=0',
+            '-c:v', 'libvpx', str(self.video),
+        ], check=True, capture_output=True)
+
+    def encode(self, source=None, *options):
+        return subprocess.run([
+            sys.executable, str(SCRIPT), str(source or self.video), str(self.output), *options,
+        ], capture_output=True, text=True)
+
+    def assert_color(self, seconds, channel):
+        result = subprocess.run([
+            'ffmpeg', '-v', 'error', '-i', str(self.output), '-ss', str(seconds),
+            '-frames:v', '1', '-vf', 'scale=1:1', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-',
+        ], check=True, capture_output=True)
+        pixel = result.stdout
+        self.assertEqual(len(pixel), 3)
+        self.assertGreater(pixel[channel], 200)
+        self.assertTrue(all(value < 40 for index, value in enumerate(pixel) if index != channel))
+
+    def test_video_trim_speed_final_hold_and_palette_order(self):
+        result = self.encode(None, '--start', '1', '--end', '5', '--speed', '2',
+                             '--final-hold', '1', '--max-width', '32')
+        self.assertEqual(result.returncode, 0, result.stderr)
+        summary = json.loads(result.stdout)
+        self.assertAlmostEqual(summary['durationSeconds'], 3, delta=0.2)
+        self.assertEqual((summary['width'], summary['height']), (32, 24))
+        self.assert_color(0.1, 0)
+        self.assert_color(0.8, 1)
+        self.assert_color(2.7, 2)
+
+    def test_video_defaults_keep_full_duration(self):
+        result = self.encode()
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertAlmostEqual(json.loads(result.stdout)['durationSeconds'], 8, delta=0.2)
+        self.assert_color(7.7, 2)
+
+    def test_invalid_video_options_do_not_write_output(self):
+        for options in [
+            ['--start', '-1'], ['--speed', 'nan'], ['--final-hold', 'inf'],
+            ['--start', '3', '--end', '3'], ['--end', '7'],
+            ['--speed', '1000'], ['--durations', '2'], ['--pattern', '*.png'],
+        ]:
+            with self.subTest(options=options):
+                result = self.encode(None, *options)
+                self.assertNotEqual(result.returncode, 0)
+                self.assertIn('error:', result.stderr)
+                self.assertFalse(self.output.exists())
+
+    def test_screenshot_durations_and_video_flag_rejection(self):
+        frames = self.root / 'frames'
+        frames.mkdir()
+        for index, color in enumerate([b'\xff\x00\x00', b'\x00\x00\xff']):
+            (frames / f'{index}.ppm').write_bytes(b'P6\n64 48\n255\n' + color * (64 * 48))
+        rejected = self.encode(frames, '--speed', '1')
+        self.assertNotEqual(rejected.returncode, 0)
+        self.assertIn('require a video file', rejected.stderr)
+        for options in [['--pattern', ''], ['--pattern', '*.ppm', '--durations', ''],
+                        ['--pattern', '*.ppm', '--durations', '1,2,3']]:
+            with self.subTest(options=options):
+                self.assertNotEqual(self.encode(frames, *options).returncode, 0)
+                self.assertFalse(self.output.exists())
+        result = self.encode(frames, '--pattern', '*.ppm', '--durations', '0.5,1.5')
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(json.loads(result.stdout)['sourceFrames'], 2)
+        self.assert_color(0.1, 0)
+        self.assert_color(1.8, 2)
+
+    def test_overwrite_and_size_limit(self):
+        self.output.write_bytes(b'keep')
+        rejected = self.encode()
+        self.assertNotEqual(rejected.returncode, 0)
+        self.assertEqual(self.output.read_bytes(), b'keep')
+        oversized = self.encode(None, '--force', '--max-bytes', '1', '--final-hold', '0.0')
+        self.assertNotEqual(oversized.returncode, 0)
+        self.assertIn('above --max-bytes', oversized.stderr)
+
+
+if __name__ == '__main__':
+    unittest.main()