Merge remote-tracking branch 'origin/main' into posthog-code/command-center-brainrot-mode

Author: richardsolomou

.claude/skills/onboarding-videos/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: onboarding-videos
+description: Add, replace, and optimize the looping demo videos in the onboarding "welcome" bento grid (packages/ui/src/features/onboarding). Covers the ffmpeg compression workflow (the scripts/optimize-onboarding-videos.mjs wrapper), the faststart + right-size best practices that keep playback smooth, the first-frame poster convention, and how to wire a new clip into WelcomeScreen. Use when onboarding demo clips feel laggy, when a clip is being added/swapped/re-recorded, or when posters and videos drift out of sync.
+allowed-tools: Bash(node scripts/optimize-onboarding-videos.mjs:*), Bash(pnpm optimize:onboarding-videos:*), Bash(ffmpeg:*), Bash(ffprobe:*), Bash(npx biome check:*), Bash(pnpm --filter @posthog/ui typecheck:*)
+---
+
+# Onboarding bento demo videos
+
+The first onboarding step (`WelcomeScreen`) shows a bento grid of feature cards.
+A card with a `media` entry plays a short, muted, looping screen recording; cards
+without one show a static placeholder. The featured (large, top-left) card is the
+only one that plays at a time — hover just moves the highlight.
+
+| Thing | Where |
+| --- | --- |
+| Clips + posters | `packages/ui/src/features/onboarding/assets/<feature>-<light\|dark>.{mp4,jpg}` |
+| Wiring (`MEDIA` map, `startTime`) | `packages/ui/src/features/onboarding/components/WelcomeScreen.tsx` |
+| `<video>` element + play/seek logic | `packages/ui/src/features/onboarding/components/FeatureBentoCard.tsx` |
+| Optimizer script | `scripts/optimize-onboarding-videos.mjs` (`pnpm optimize:onboarding-videos`) |
+
+## Why clips need optimizing (the "it feels laggy" fix)
+
+Raw screen recordings hitch in this UI for two reasons, both fixed by re-encoding:
+
+1. **`moov` atom at the end of the file.** Without faststart the player must read
+   to EOF before it can start, so first-play and every seek stutter. We seek on
+   mount and on every loop (`FeatureBentoCard` parks the clip on `videoStartTime`),
+   so this bites constantly. Fix: `-movflags +faststart`.
+2. **Resolution far larger than it renders.** The featured slot is never wider than
+   ~500 CSS px (the grid is `max-w-[760px]`). Even at 2× retina that's ~1000px, but
+   recordings come in at ~1876px. Decoding huge frames and downscaling them — on
+   every play and during the framer-motion slot reflow — is wasted work. Fix: cap
+   width at **1000px** (which also matches the poster width exactly).
+
+Bitrate/size are usually already modest; **decode cost and startup are the lag**,
+not bytes. Don't chase file size at the expense of width/faststart.
+
+## Canonical encode target
+
+H.264 · `yuv420p` · **≤1000px wide** (keep aspect, even height) · CRF 23 ·
+`+faststart` · no audio. These live as constants at the top of
+`scripts/optimize-onboarding-videos.mjs` — change them there, not ad-hoc.
+
+## Optimize existing clips
+
+```bash
+pnpm optimize:onboarding-videos          # encode any clip not already optimized
+pnpm optimize:onboarding-videos --dry-run   # show what would change
+pnpm optimize:onboarding-videos --force     # re-encode all (after changing the target constants)
+```
+
+Requires ffmpeg (`brew install ffmpeg`). The script tags each output with a
+`comment` marker, so re-runs skip already-optimized files — it's safe to run any
+time, including right after dropping in a new clip. It rewrites files in place;
+review the `git diff --stat` and the printed before/after sizes.
+
+## Add or replace a clip
+
+1. **Record** light + dark variants at **≥1000px wide**. The optimizer downscales to
+   1000px but never upscales, so anything narrower ships soft — resolution is the one
+   thing it can't fix for you. Keep it short (~10–13s); it loops.
+2. **Name + drop** the files as `assets/<feature>-light.mp4` and
+   `assets/<feature>-dark.mp4`. Two things bite every time:
+   - Recordings almost always arrive with the **light variant unsuffixed**
+     (`foo.mp4`, only `foo-dark.mp4` is tagged). Rename it to `foo-light.mp4`.
+   - The source filename (e.g. whatever's in `~/Downloads`) is irrelevant — the
+     `<feature>` prefix must be the **media id** you'll use in `WelcomeScreen` and
+     follow the existing convention, not whatever the file was called.
+
+   No `assets.d.ts` change needed — `*.mp4`/`*.jpg` are wildcard modules.
+3. **Optimize**: `pnpm optimize:onboarding-videos`.
+4. **Make the poster** — the still shown before play. **Use the clip's first frame**
+   and leave `startTime` at 0, so the poster, the first played frame, and the loop
+   point are all the same with nothing to keep in sync:
+
+   ```bash
+   ffmpeg -y -i assets/<feature>-<theme>.mp4 \
+     -frames:v 1 -vf "scale=1000:-2:flags=lanczos" -q:v 3 \
+     assets/<feature>-<theme>.jpg
+   ```
+
+5. **Wire it up** in `WelcomeScreen.tsx`. For a *new* media id, four edits, all keyed
+   by the same slug: import the `.mp4` + `.jpg`, add the id to the `MediaId` union,
+   add its entry to the `MEDIA` map (`startTime: 0`), and set `media: "<id>"` on the
+   target `FeatureDef`.
+
+### Replacing an existing clip
+
+Keep the **same asset filename** and the wiring is untouched — none of step 5
+applies. Drop the new file over `assets/<feature>-<theme>.mp4`, run the optimizer (a
+fresh drop carries no skip-marker, so it re-encodes without `--force`), and
+**regenerate that poster** (step 4). If you replace only one theme, re-check that
+light and dark still share an aspect ratio — a clip with stray padding frames
+differently from its sibling, and the gap shows when the user toggles theme.
+
+## Poster = first frame (and startTime = 0)
+
+`FeatureBentoCard` shows the poster while a card rests, then seeks the `<video>` to
+`MEDIA[id].startTime` on mount and loops back there (not necessarily to 0). The
+simple, default contract: **the poster is the clip's first frame and `startTime` is
+0**, so the still, the first played frame, and the loop point are all identical —
+nothing to keep in sync. Keep the poster the same pixel width as the clip (1000px)
+so the poster→video swap is seamless.
+
+`startTime` can start/loop mid-clip if you ever need it (the `code-review` clip uses
+3s) — but then the poster MUST be that exact frame (`ffmpeg -ss <startTime> -i …`),
+or the still jumps the instant playback starts. Prefer the first-frame default
+unless you have a specific reason.
+
+## Verify
+
+```bash
+# clips: moov should print BEFORE mdat, width ≤ 1000:
+ffprobe -v trace <clip>.mp4 2>&1 | grep -o -m2 -E "type:'(moov|mdat)'"
+ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 <clip>.mp4
+
+# wiring: a grown MediaId union may need a formatter reflow, so let biome fix it:
+npx biome check --write packages/ui/src/features/onboarding/components/WelcomeScreen.tsx
+pnpm --filter @posthog/ui typecheck
+```
+
+To confirm playback feels smooth in the real app, use the `test-electron-app`
+skill to drive the running onboarding flow.

.claude/skills/test-electron-app/SKILL.md

@@ -50,17 +50,18 @@ pnpm build:deps                        # turbo build of @posthog/code deps
 tail -f /dev/null | pnpm dev:code      # run in the background; leave it running
 ```
 
-`pnpm dev:code` is `electron-forge start -- --remote-debugging-port=9222` — just
-the app, no TUI and no watch rebuilders (fine for screenshotting/interacting).
-
-**The `tail -f /dev/null |` is required, do not drop it.** `electron-forge start`
-runs an interactive "type `rs` to restart" stdin reader. With no stdin it hits
-EOF immediately, treats that as quit, tears down the Electron window, and exits
-**0** before the CDP port ever opens — so the app looks like it launched
-("✔ Launched Electron app") and then silently vanishes. Piping from
-`tail -f /dev/null` gives it a stdin that never closes, so it stays up. A
-pseudo-TTY via `script` does **not** help: `script` forwards the EOF (`^D`) and
-the app still quits.
+`pnpm dev:code` is `pnpm --filter code start`, i.e. `electron-vite dev --watch` — just
+the app, no `phrocs` TUI; it watches and rebuilds main/preload and hot-reloads the
+renderer (fine for screenshotting/interacting). The CDP port (`:9222`) is opened by
+the app itself in dev (the `remote-debugging-port` switch in
+`apps/code/src/main/bootstrap.ts`), not by a CLI flag.
+
+The `tail -f /dev/null |` prefix is a harmless guard and no longer strictly required.
+The old `electron-forge start` ran an interactive "type `rs` to restart" stdin reader
+that hit EOF in a no-stdin shell, treated it as quit, and tore the Electron window
+down before the CDP port ever opened. `electron-vite dev` has no such reader, so a
+backgrounded `pnpm dev:code` with no stdin stays up on its own; keeping the pipe does
+no harm.
 
 Then wait for the port and connect (poll, don't sleep blindly):
 
@@ -113,7 +114,7 @@ rm -f /tmp/posthog-dev-lastuse
 ```
 
 Group-killing the launcher (`kill -TERM -PGID`) takes down `tail`, `pnpm`,
-`electron-forge` and Electron together, so nothing — not even the
+`electron-vite` and Electron together, so nothing — not even the
 `tail -f /dev/null` stdin pipe — lingers. Matching `remote-debugging-port=9222`
 hits only your dev instance (prod has no debug port and a separate
 `posthog-code-dev` profile), so it never touches the user's app. Verify with
@@ -212,11 +213,12 @@ PostHog Code orchestrates the agent, so the usual loop is: **prod** (the install
 - **Connection refused on :9222:** the app isn't running with the debug flag.
   Start it (see *Launching the app yourself* for the headless recipe). Verify the
   port: `lsof -i :9222` or `curl -s localhost:9222/json/version`.
-- **App launches then immediately exits 0; CDP never opens:** you started it with
-  no stdin (background / no TTY) and `electron-forge` quit on stdin EOF. Relaunch
-  with `tail -f /dev/null | pnpm dev:code` so stdin never closes (see *Launching
-  the app yourself*). Note `pnpm dev` cannot run headlessly at all — its `phrocs`
-  TUI needs a TTY; use `pnpm dev:code`.
+- **App launches then immediately exits; CDP never opens:** the old `electron-forge`
+  "quit on stdin EOF" behavior is gone under `electron-vite`, so the
+  `tail -f /dev/null |` prefix is optional and not the fix here. This is now usually a
+  build error, the single-instance lock (another dev instance running) or a crash —
+  check the `pnpm dev:code` output. Note `pnpm dev` cannot run headlessly at all — its
+  `phrocs` TUI needs a TTY; use `pnpm dev:code`.
 - **Snapshot is empty / wrong window:** you're on the wrong target. Run
   `agent-browser tab` and switch to the "PostHog Code" page.
 - **Can't type into an input:** try `agent-browser keyboard type "text"` (types at

.github/workflows/agent-release.yml

@@ -23,10 +23,10 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
 
       - name: Set up Node 24
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
           cache: "pnpm"

.github/workflows/agent-tag.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - name: Get app token
         id: app-token
-        uses: getsentry/action-github-app-token@d4b5da6c5e37703f8c3b3e43abb5705b46e159cc # v3.0.0
+        uses: getsentry/action-github-app-token@5c1e90706fe007857338ac1bfbd7a4177db2f789 # v4.0.0
         with:
           app_id: ${{ secrets.GH_APP_ARRAY_RELEASER_APP_ID }}
           private_key: ${{ secrets.GH_APP_ARRAY_RELEASER_PRIVATE_KEY }}

.github/workflows/build.yml

@@ -18,7 +18,7 @@ jobs:
     steps:
       - name: Detect relevant changes
         id: filter
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         with:
           predicate-quantifier: every
           filters: |
@@ -51,10 +51,10 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
 
       - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 22
           cache: "pnpm"