@sentry/junior-agent-browser 0.234.0 → 0.236.0

package/README.md

@@ -16,10 +16,11 @@ import { defineJuniorPlugins } from "@sentry/junior";
 export const plugins = defineJuniorPlugins(["@sentry/junior-agent-browser"]);
 ```
 
-The package includes two skills:
+The package includes three skills:
 
 - `/agent-browser` for general browser navigation, interaction, extraction, and capture
 - `/visual-web-qa` for evidence-driven verification of frontend, docs, layout, theme, loading, animation, and interaction changes
+- `/demo-video` for edited product presentations with browser captures, optional narration, and Remotion
 
 For example:
 
@@ -27,4 +28,6 @@ For example:
 /visual-web-qa Verify the docs theme on desktop and mobile, then share the evidence.
 ```
 
+`/demo-video` captures the production workflow; it does not install Remotion or FFmpeg. Use a local artifact project with compatible dependencies and an appropriate Remotion license. For generated narration, enable a TTS plugin such as `@sentry/junior-tts`, or supply an audio file. Keep video artifacts separate from the app unless a repository change is requested.
+
 Full setup guide: https://junior.sentry.dev/extend/agent-browser-plugin/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-agent-browser",
-  "version": "0.234.0",
+  "version": "0.236.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/skills/demo-video/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: demo-video
+description: Creates and revises product demo videos and narrated walkthroughs from browser captures with Remotion. Use for a short presentation of an app or shipped work, animated screenshots, or a video update with new narration. Do not use for a raw browser recording, screenshot-only visual QA, or audio-only text-to-speech.
+---
+
+# Demo Video
+
+Make the product the subject. Show what people can do, why it matters, and what the team built. Use personality in the delivery, not as the story. Do not introduce a revision as a new take or talk about the narrator's voice unless asked.
+
+Open [references/rendering.md](references/rendering.md) when setting up Remotion, measuring clips, rendering, or checking an export. It includes commands and revision examples.
+
+## 1. Resolve The Brief And Reuse Work
+
+- Read the current request and prior decisions. Keep the agreed audience, length, tone, credits, and destination. Ask only for a missing decision that blocks work.
+- Find the existing source, assets, and attachments before rebuilding. If the source is missing, say this will be a fresh composition.
+- Inspect the target UI and relevant repository history before writing claims about shipped behavior. Use the repository skill for code access. Do not present an unmerged feature as live.
+- Draft a short scene list with one point per scene. Match each claim to a capture or verified source. Name collaborators when requested and supported.
+- Separate product capabilities from actions taken during this task. Describing reminder emails does not authorize sending one.
+
+## 2. Capture The Actual UI
+
+Load `agent-browser` for browser commands. Use `visual-web-qa` when the request also asks whether the UI works or looks correct.
+
+- Prefer a reachable local or preview page for the requested revision. Use an authorized session for private pages; do not bypass sign-in.
+- If private data prevents safe capture, use the real UI with isolated synthetic fixtures. Label that data in the video. Do not make a lookalike and call it the app.
+- Keep the fixture server local. Prevent it from sending writes, email, or uploads to production. Do not reuse customer submissions or secrets.
+- Capture a few useful states and relevant desktop/mobile views. Save the route, viewport, theme, and source revision with each asset.
+- Use screenshots for stable pages. Use short browser recordings when an interaction or motion is part of the story. Stop recordings after the required flow.
+- Wait for expected content and fonts. Open the captures before using them. Check for loading states, clipping, mismatched fixture counts, and sensitive content.
+
+For a raw interaction recording without an edited presentation, use `agent-browser` alone. Do not add a Remotion project by default.
+
+## 3. Prepare Narration
+
+- Write spoken text separately from scene layout and delivery directions. Keep the opening about the work. Put credits and operational capabilities where they support the story.
+- For requested speech, load the available TTS skill and use its credential, cost, and retry rules. Use the agreed voice preset. Do not silently replace a missing provider with another voice.
+- Generate one clip per scene to make revisions cheap. Reuse unchanged clips and generate changed text to fresh paths. A visual-only edit needs no new speech request.
+- Measure each clip. Derive scene frames from its duration plus explicit lead and tail time. Recompute later scene offsets after a clip changes.
+- Keep captions tied to the final script. Use real alignment when available; otherwise state that word-count timing is approximate. Audio-energy avatar motion is not lip sync.
+
+## 4. Compose And Render
+
+- Use a separate artifact directory unless the user asked to change the app. Keep composition source, local assets, scene data, and outputs together.
+- Reuse an existing Remotion project and lockfile. For a new project, follow the setup reference. Browser runtime setup remains owned by the plugin; report a missing runtime instead of repairing it here.
+- Match the app's type, colors, and approved assets. Keep UI text readable. Use simple cuts, pans, and small transitions instead of expensive effects.
+- Bundle images, fonts, and audio locally. Drive motion from frame numbers, not wall-clock timers or network calls during render.
+- Render stills for each layout before a full video. Start with low concurrency in a small Sandbox. Use a short frame range to diagnose failures.
+- Set export resolution and audio bitrate for the destination early. Keep the source at full composition size. A smaller delivery copy need not change the scene design.
+
+## 5. Check And Deliver
+
+- Decode the full exported video and audio. Inspect frames from every scene, including transitions, first/last frames, captions, and any changed crop. Check durations, missing audio, peaks, and final-frame truncation.
+- Listen when audio review is available. Decode and level checks do not prove pronunciation, timing, or listening quality; report unchecked limits.
+- Check the actual file size before attachment. If too large, re-encode the existing master with a smaller delivery profile. Recheck that file. Do not regenerate speech or publish a public URL to work around the limit.
+- Inspect outputs and logs after a timeout before repeating a render. Never infer success from a file's existence alone.
+- Deliver the video with `sendFiles`. Include standalone synthetic narration and editable source when requested or already agreed. Exclude dependencies, caches, secrets, and unused revisions from the source archive.
+- Report successful attachments, duration, checks, and remaining limits. Record capture provenance and rerender commands in the artifact README. Do not say the app or production changed when only the video changed.

package/skills/demo-video/SOURCES.md

@@ -0,0 +1,44 @@
+# Demo Video Sources
+
+## Source Inventory
+
+Reviewed 2026-09-29. Official docs and repository contracts are authoritative for syntax and ownership. The completed workflow is evidence of one working setup, not a performance guarantee.
+
+| Source                                                                            | Confidence                 | Contribution and limits                                                                                                                                                                                  |
+| --------------------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Agent Skills specification](https://agentskills.io/specification)                | High                       | Frontmatter, directory names, and relative bundled files.                                                                                                                                                |
+| `packages/junior-agent-browser/plugin.yaml`, package manifest, and sibling skills | High                       | Browser ownership and packaged skill discovery. Keep runtime setup in the manifest.                                                                                                                      |
+| `packages/junior-tts/skills/tts/SKILL.md`                                         | High                       | Speech workflow, fresh paths, provider ownership, and paid-request limits. Reference rather than duplicate its credential policy.                                                                        |
+| `policies/agent-steering.md`                                                      | High                       | One owner per rule. No extra system prompt or core tool changes.                                                                                                                                         |
+| [Remotion render CLI](https://www.remotion.dev/docs/cli/render)                   | High                       | Composition selection, codec, frame range, scale, concurrency, audio bitrate, and overwrite controls. Check flags against the installed version.                                                         |
+| [Remotion performance](https://www.remotion.dev/docs/performance)                 | High                       | Concurrency tradeoffs, local assets, resolution, and expensive GPU effects. No universal fastest setting.                                                                                                |
+| [Remotion versions](https://www.remotion.dev/docs/version-mismatch)               | High                       | Exact, matching Remotion package versions.                                                                                                                                                               |
+| [Remotion licensing](https://www.remotion.dev/docs/license)                       | High                       | Commercial use has license conditions; no free-use assumption.                                                                                                                                           |
+| Completed browser-to-Remotion presentation and user revisions, September 2026     | High for observed outcomes | Real React UI with local fixtures; measured WAV clips; Remotion 4.0.354; FFmpeg decode and frame checks; successful MP4, WAV, and source delivery. Generalized here without transcript or identity data. |
+
+Documentation is linked and summarized, not copied as a bundled upstream manual. No third-party media, project-specific avatar, sample app data, or generated speech is included.
+
+## Decisions And Coverage
+
+- **Adopted:** general Junior ownership in the existing browser plugin. Browser capture is the entry point. The workflow is not specific to one app or deployment.
+- **Adopted:** workflow-process class and reference-backed shape. The main checklist is short; exact rendering commands are a separate lookup. Inline-only guidance would mix story decisions with optional CLI detail.
+- **Adopted:** product-led narration, requested collaborator credit, and supported capability claims. User corrections rejected voice-focused introductions and take numbers.
+- **Adopted:** reuse unchanged speech and captures. Measure new clips and update later scene starts. This reduced paid generation during small edits.
+- **Adopted:** inspect output after timeouts; check actual attachment bytes. One render completed despite a tool timeout. A large master needed a smaller delivery copy.
+- **Adopted:** standard-library WAV measurement fallback. FFmpeg was available while FFprobe was not. No extra audio package was needed.
+- **Rejected:** shipping the one-off composition, fixtures, assets, or hardcoded browser path. Those are project choices, not reusable skill policy.
+- **Deferred:** a Remotion plugin, installed render dependencies, generator scripts, forced caption alignment, and phoneme-level avatar animation. No recurring need for that scope was established.
+
+Coverage includes preconditions (brief, source, tools, license), ordered flow (capture through delivery), safety (local fixtures and no production actions), failures (auth, missing tools, timeout, size), revision examples, and verified output limits. All runtime reference files are routed directly from `SKILL.md`.
+
+Portability: pnpm, Node, Remotion, an installed browser, and FFmpeg are explicit. TTS is optional and delegated to the installed skill. Python is only a conditional WAV fallback. No host path, provider token, or model name is required by this skill.
+
+## Precision And Validation Notes
+
+Added one skill because neither browser automation nor visual QA owns edited presentation production. Kept those workflows unchanged. Moved command detail and examples into one reference; provenance and trigger review stay in maintenance files. No new tool descriptions, manifests, or dependency setup rules were added.
+
+Trigger review separates edited presentations from raw capture, visual QA, audio-only work, and operating the app. Examples cover the happy path, private-data handling, story correction, capability claims, and delivery recovery.
+
+Collection stopped after the successful workflow, its observed failures, current official syntax, and repository registration rules covered the requested scope. Broader video tooling research would not change this small workflow.
+
+Open limits: this instruction-only addition has structural and manual content checks, not a new model-graded execution eval. Rendering commands came from the observed workflow and official docs; future environments must check dependencies, licenses, and destination limits. No new paid narration is needed to validate this skill change.

package/skills/demo-video/SPEC.md

@@ -0,0 +1,47 @@
+# Demo Video Specification
+
+## Intent And Scope
+
+Create or revise an edited product presentation from real UI captures, optional narration, and a Remotion composition. Keep the story about the product and the team's work. Preserve useful source and assets across revisions.
+
+This is a workflow-process skill with a reference-backed shape. The runtime checklist owns the flow. One reference holds optional rendering commands and examples. No generator script, fixed design template, new package, or runtime dependency is required by this change.
+
+Raw browser recordings belong to `agent-browser`. Visual correctness checks belong to `visual-web-qa`. Audio-only requests belong to the available TTS skill. Deployment, event operations, email sending, and voice cloning are outside scope.
+
+## Contract
+
+- Resolve the brief, source, and existing artifacts before generating assets.
+- Verify product claims and preserve requested credits.
+- Capture the real UI safely; label synthetic fixtures and narration.
+- Measure speech, reuse unchanged clips, and keep scene offsets current.
+- Check the delivered export, not only its source or master.
+- Deliver the requested video and agreed supporting artifacts with honest limits.
+- Leave the app and production unchanged unless a separate request permits changes.
+
+## Trigger Review
+
+Should trigger:
+
+- “Make a short product demo with animated screenshots and narration.”
+- “Use Remotion to present what we shipped.”
+- “Update this demo video with the new UI and voiceover.”
+- “Add a collaborator credit and the reminder feature to our presentation.”
+
+Should not trigger:
+
+- “Record this loading bug.”
+- “Take a mobile screenshot and check the spacing.”
+- “Read this paragraph aloud.”
+- “Schedule a demo and send an email reminder.”
+
+## Evidence And Validation
+
+Use the repository, safe browser captures, measured media, render logs, and user feedback. See `SOURCES.md` for provenance. Store no raw Slack transcript, secrets, private submissions, or identifying fixture data in this skill.
+
+Validate frontmatter, bundled links, plugin packaging, and the trigger boundary. Manually review the examples for product focus, blocked authentication, scoped clip reuse, and oversized delivery. A future execution should render a short sample and verify decoding and representative frames. Structural checks do not prove narration quality or agent behavior.
+
+## Limits And Maintenance
+
+Remotion and FFmpeg are not provisioned by this skill. Speech needs the appropriate enabled plugin or supplied audio. Commercial Remotion use needs an appropriate license. Captions based on word counts remain approximate. Audio-energy motion is not lip sync.
+
+Update commands after incompatible Remotion changes. Keep tool setup and credentials in their owning plugins. Extend the existing reference only for a demonstrated failure or recurring task; do not turn this into a general video platform.

package/skills/demo-video/references/rendering.md

@@ -0,0 +1,111 @@
+# Render And Revise A Demo
+
+## Project Setup
+
+Check Node.js, pnpm, FFmpeg, and an installed supported browser before rendering. Use the browser executable path found in the current Sandbox, not a saved path from another run. FFprobe is optional; it may be absent even when FFmpeg is present.
+
+This skill ships instructions, not Remotion or FFmpeg. Do not install or repair the browser plugin runtime here. If an external dependency is unavailable or installation is not permitted, report the missing dependency. Check the organization's Remotion license before commercial use; do not assume the free license applies.
+
+Keep a new project outside the app checkout:
+
+```text
+demo-video/
+  package.json
+  pnpm-lock.yaml
+  src/index.tsx
+  src/scenes.json
+  public/
+  out/
+  README.md
+```
+
+For a new, authorized local artifact project, choose a verified compatible version. Replace the placeholders before running:
+
+```bash
+pnpm add --save-exact remotion@<version> @remotion/cli@<same-version> react@<version> react-dom@<same-version>
+```
+
+All Remotion packages must have the same exact version. Reuse the lockfile on revisions. Check the installed CLI help and current docs before adding version-specific flags.
+
+Use `registerRoot` and `Composition` for the entry point. Load local media with `staticFile` and `Img`. Put each scene and its audio in a `Sequence`. Use `useCurrentFrame`, `interpolate`, or `spring` for deterministic motion. Use media components supported by the installed version.
+
+Keep scene text, asset path, audio path, measured seconds, start frame, and duration in one scene record. Do not select clips through scattered filename conditions. Keep original screenshots; derive crops as separate assets.
+
+## Measure Audio Before Setting Frames
+
+When FFprobe is available:
+
+```bash
+ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 public/scene.wav
+```
+
+For PCM WAV files, Python's standard library is a fallback when Python is available:
+
+```bash
+python3 - <<'PY'
+import wave
+with wave.open('public/scene.wav', 'rb') as clip:
+    print(clip.getnframes() / clip.getframerate())
+PY
+```
+
+For each scene:
+
+```text
+audioFrames = ceil(audioSeconds * fps)
+sceneFrames = leadFrames + audioFrames + tailFrames
+startFrame = sum(previous sceneFrames)
+```
+
+Place audio at `leadFrames` within the scene. Ensure fades do not cut off speech. Caption times use the same audio offset. Never keep an old duration after replacing a clip.
+
+## Preview, Then Render
+
+Run from the artifact project. Replace the entry point, composition ID, frame, and output names as needed. Use fresh output names. Add `--browser-executable="$BROWSER"` only after resolving that path.
+
+```bash
+pnpm exec remotion still src/index.tsx Demo out/layout.png --frame=60
+pnpm exec remotion render src/index.tsx Demo out/sample.mp4 --frames=0-89 --codec=h264 --concurrency=2
+pnpm exec remotion render src/index.tsx Demo out/demo.mp4 --codec=h264 --crf=26 --audio-bitrate=128k --concurrency=2 --overwrite=false
+```
+
+- Use local assets and simple transforms. Precompute audio levels or caption boundaries once, not per frame.
+- Avoid blur, large shadows, and complex effects on a CPU-only Sandbox.
+- Start at concurrency 2 if resources permit. More workers can make rendering slower or exhaust memory. Measure a short sample before increasing it.
+- For a 1920 × 1080 composition, `--scale=0.6666666666666666` produces a 1280 × 720 copy. Scaling is not a file-size guarantee.
+- Keep long-render logs in a file. On timeout, inspect the log and output before rerunning. A failed render does not require new narration.
+
+## Export Checks And Size
+
+```bash
+# Inspect streams and duration. With no output, FFmpeg normally exits nonzero.
+# This is a metadata probe, not a validation result.
+ffmpeg -hide_banner -i out/demo.mp4
+
+# Decode both streams completely. Check the exit code and stderr.
+ffmpeg -v error -i out/demo.mp4 -f null -
+
+# Measure audio level; this is not a listening check.
+ffmpeg -hide_banner -i out/demo.mp4 -vn -af volumedetect -f null -
+
+# Seek directly to a representative frame instead of decoding the full film per still.
+ffmpeg -v error -ss 12 -i out/demo.mp4 -frames:v 1 -update 1 out/frame.png
+```
+
+Extract and inspect representative frames from all scenes and changed transitions. Keep captions outside the UI crop. Do not treat a contact sheet as proof that motion or speech timing is correct.
+
+Check the destination's current limit and the file's byte size. Do not assume the upload limit from a previous conversation still applies. If necessary, re-encode the existing master:
+
+```bash
+ffmpeg -n -i out/demo.mp4 -vf scale=1280:720 -c:v libx264 -preset medium -crf 28 -c:a aac -b:a 96k -movflags +faststart out/demo-delivery.mp4
+```
+
+Measure the new file and check its text readability and decoding. If it still exceeds the limit, reduce resolution or bitrate while preserving usable UI text. Keep the original master. For standalone narration, join the original lossless clips with the same scene gaps; do not decode the compressed MP4 audio when source WAV files are available.
+
+## Revision Examples
+
+- **Product walkthrough:** “Present what we built in about 90 seconds.” Inspect the UI and shipped changes, capture four useful states, write a benefit-led script, then generate and measure scene clips. Deliver an MP4 and the agreed source archive.
+- **Private app:** “Use our dashboard in a demo.” Sign-in blocks access. Use an authorized session or the real local UI with isolated, labeled synthetic fixtures. State that this is not a production-data recording. Do not copy private submissions or alter production to make the capture work.
+- **Story correction:** “This is about the product, not your new voice.” Bad: regenerate everything and announce “take three.” Correct: remove voice and take references from spoken and on-screen text, replace only changed clips, recompute timing, and keep useful captures.
+- **Add credit and operations:** “Name my collaborator and explain reminders.” Verify the name and capability. Add the credit and a short workflow explanation, including required confirmation. Do not send a reminder just to illustrate it.
+- **Upload rejected:** a valid MP4 exceeds the attachment limit. Keep its narration and composition. Make a smaller delivery copy, check it, and resend that file rather than repeating paid generation.