argos-harness 0.1.0

package/assets/skills/promo-video/assets/promo.template.tsx

@@ -0,0 +1,469 @@
+// Scene architecture template — verified on a real render.
+// Replace SCREENSHOT_ASPECT, scene copy, screenshot filenames, and lockup text
+// with the target app's values. Copy language = the store listing's locale.
+import React from 'react';
+import {
+  AbsoluteFill,
+  Audio,
+  Img,
+  interpolate,
+  spring,
+  staticFile,
+  useCurrentFrame,
+  useVideoConfig,
+} from 'remotion';
+import {TransitionSeries, linearTiming} from '@remotion/transitions';
+import {fade} from '@remotion/transitions/fade';
+import {slide} from '@remotion/transitions/slide';
+import {colors, fonts, radialBackground} from './theme';
+
+// Real pixel ratio of the source screenshots (width / height).
+const SCREENSHOT_ASPECT = 1320 / 2868;
+
+// Scene durations (frames @ 30fps). Transitions overlap TRANSITION_FRAMES each:
+// total = sum(durations) - (transitions * TRANSITION_FRAMES). Tune to hit target.
+export const DURATIONS = {
+  intro: 110,
+  feature1: 145,
+  feature2: 145,
+  feature3: 145,
+  feature4: 130,
+  outro: 135,
+};
+const TRANSITION_FRAMES = 12;
+export const TOTAL_DURATION =
+  Object.values(DURATIONS).reduce((a, b) => a + b, 0) - 5 * TRANSITION_FRAMES;
+
+const springIn = (frame: number, fps: number, delay = 0) =>
+  spring({frame: frame - delay, fps, config: {damping: 16}});
+
+const Backdrop: React.FC<{children: React.ReactNode}> = ({children}) => (
+  <AbsoluteFill style={{background: radialBackground}}>{children}</AbsoluteFill>
+);
+
+// Giant outlined word drifting behind feature scenes for depth.
+const Watermark: React.FC<{word: string}> = ({word}) => {
+  const frame = useCurrentFrame();
+  const {durationInFrames} = useVideoConfig();
+  const drift = interpolate(frame, [0, durationInFrames], [0, -18]);
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: 260,
+        left: -120,
+        fontFamily: fonts.display,
+        fontWeight: 700,
+        fontSize: 340,
+        textTransform: 'uppercase',
+        letterSpacing: 8,
+        whiteSpace: 'nowrap',
+        color: 'transparent',
+        WebkitTextStroke: '1px rgba(250,250,250,0.05)',
+        transform: `translateX(${drift}px)`,
+      }}
+    >
+      {word}
+    </div>
+  );
+};
+
+// Staggered copy block: eyebrow, headline, body — 5 frames apart.
+const HeadlineBlock: React.FC<{
+  eyebrow: string;
+  headline: string;
+  body: string;
+  delay?: number;
+}> = ({eyebrow, headline, body, delay = 8}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+  const rows = [
+    {
+      text: eyebrow,
+      style: {
+        fontFamily: fonts.display,
+        fontWeight: 600,
+        fontSize: 30,
+        letterSpacing: 5,
+        textTransform: 'uppercase' as const,
+        color: colors.accent,
+      },
+    },
+    {
+      text: headline,
+      style: {
+        fontFamily: fonts.display,
+        fontWeight: 700,
+        fontSize: 72,
+        letterSpacing: 2,
+        textTransform: 'uppercase' as const,
+        color: colors.textPrimary,
+        lineHeight: 1.05,
+      },
+    },
+    {
+      text: body,
+      style: {
+        fontFamily: fonts.body,
+        fontWeight: 500,
+        fontSize: 34,
+        color: colors.textSecondary,
+      },
+    },
+  ];
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: 130,
+        left: 0,
+        right: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 20,
+        textAlign: 'center',
+        padding: '0 80px',
+      }}
+    >
+      {rows.map((row, i) => {
+        const s = springIn(frame, fps, delay + i * 5);
+        return (
+          <div
+            key={row.text}
+            style={{
+              ...row.style,
+              opacity: s,
+              transform: `translateY(${interpolate(s, [0, 1], [40, 0])}px)`,
+            }}
+          >
+            {row.text}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+// CSS device frame with entrance spring, perspective tilt settling to a
+// small residual (never fully flat — keeps depth), and a slow sine float.
+const Phone: React.FC<{
+  src: string;
+  enterFrom: 'bottom' | 'left' | 'right';
+  tiltY: number;
+}> = ({src, enterFrom, tiltY}) => {
+  const frame = useCurrentFrame();
+  const {fps, height} = useVideoConfig();
+  const enter = springIn(frame, fps, 4);
+
+  const phoneHeight = height * 0.62;
+  const phoneWidth = phoneHeight * SCREENSHOT_ASPECT;
+
+  const offset = interpolate(enter, [0, 1], [1, 0]);
+  const translateX =
+    enterFrom === 'left' ? -900 * offset : enterFrom === 'right' ? 900 * offset : 0;
+  const translateY = enterFrom === 'bottom' ? 1100 * offset : 0;
+
+  const rotateY = interpolate(enter, [0, 1], [tiltY, tiltY * 0.25]);
+  const rotateX = interpolate(enter, [0, 1], [2, 0.5]);
+
+  const float = Math.sin((frame / fps) * Math.PI) * 8;
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        bottom: 110,
+        left: '50%',
+        perspective: 1200,
+        transform: `translateX(-50%) translate(${translateX}px, ${translateY + float}px)`,
+      }}
+    >
+      <div
+        style={{
+          width: phoneWidth,
+          height: phoneHeight,
+          borderRadius: 64,
+          border: `10px solid ${colors.border}`,
+          backgroundColor: colors.surface,
+          overflow: 'hidden',
+          boxShadow: '0 40px 80px rgba(0,0,0,0.6)',
+          transform: `rotateY(${rotateY}deg) rotateX(${rotateX}deg)`,
+        }}
+      >
+        <Img
+          src={staticFile(src)}
+          style={{width: '100%', height: '100%', objectFit: 'cover'}}
+        />
+      </div>
+    </div>
+  );
+};
+
+// One-shot accent glow pulse behind the device — use on ONE scene only.
+const GlowPulse: React.FC = () => {
+  const frame = useCurrentFrame();
+  const opacity = interpolate(frame, [18, 40, 85], [0, 1, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        bottom: 60,
+        left: '50%',
+        transform: 'translateX(-50%)',
+        width: 1000,
+        height: 1100,
+        borderRadius: '50%',
+        background:
+          'radial-gradient(ellipse at center, rgba(220,38,38,0.25) 0%, rgba(220,38,38,0) 65%)',
+        opacity,
+      }}
+    />
+  );
+};
+
+const FeatureScene: React.FC<{
+  watermark: string;
+  eyebrow: string;
+  headline: string;
+  body: string;
+  screenshot: string;
+  enterFrom: 'bottom' | 'left' | 'right';
+  tiltY: number;
+  glow?: boolean;
+}> = ({watermark, eyebrow, headline, body, screenshot, enterFrom, tiltY, glow}) => (
+  <Backdrop>
+    <Watermark word={watermark} />
+    {glow ? <GlowPulse /> : null}
+    <Phone src={screenshot} enterFrom={enterFrom} tiltY={tiltY} />
+    <HeadlineBlock eyebrow={eyebrow} headline={headline} body={body} />
+  </Backdrop>
+);
+
+// Logo + wordmark lockup shared by intro and outro. `speed` shortens delays.
+const Lockup: React.FC<{speed?: number}> = ({speed = 1}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  const logoS = springIn(frame, fps, 2 * speed);
+  const eyebrowS = springIn(frame, fps, 22 * speed);
+  const titleS = springIn(frame, fps, 16 * speed);
+  const barS = springIn(frame, fps, 28 * speed);
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 28,
+      }}
+    >
+      <Img
+        src={staticFile('logo.png')}
+        style={{
+          width: 360,
+          height: 360,
+          opacity: logoS,
+          transform: `scale(${interpolate(logoS, [0, 1], [0.7, 1])})`,
+        }}
+      />
+      <div
+        style={{
+          fontFamily: fonts.display,
+          fontWeight: 600,
+          fontSize: 28,
+          letterSpacing: 6,
+          textTransform: 'uppercase',
+          color: colors.textSecondary,
+          opacity: eyebrowS,
+          transform: `translateY(${interpolate(eyebrowS, [0, 1], [24, 0])}px)`,
+        }}
+      >
+        APP TAGLINE
+      </div>
+      <div
+        style={{
+          fontFamily: fonts.display,
+          fontWeight: 700,
+          fontSize: 110,
+          letterSpacing: 4,
+          textTransform: 'uppercase',
+          color: colors.textPrimary,
+          lineHeight: 1,
+          opacity: titleS,
+          transform: `translateY(${interpolate(titleS, [0, 1], [70, 0])}px)`,
+        }}
+      >
+        APP NAME
+      </div>
+      <div
+        style={{
+          width: 180,
+          height: 6,
+          backgroundColor: colors.accent,
+          transformOrigin: 'left',
+          transform: `scaleX(${barS})`,
+        }}
+      />
+    </div>
+  );
+};
+
+const IntroScene: React.FC = () => (
+  <AbsoluteFill
+    style={{
+      backgroundColor: colors.bg,
+      justifyContent: 'center',
+      alignItems: 'center',
+    }}
+  >
+    <Lockup />
+  </AbsoluteFill>
+);
+
+const OutroScene: React.FC = () => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+  const ctaS = springIn(frame, fps, 26);
+  const subS = springIn(frame, fps, 34);
+
+  return (
+    <AbsoluteFill
+      style={{
+        backgroundColor: colors.bg,
+        justifyContent: 'center',
+        alignItems: 'center',
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          gap: 36,
+        }}
+      >
+        <Lockup speed={0.6} />
+        <div
+          style={{
+            fontFamily: fonts.body,
+            fontWeight: 600,
+            fontSize: 36,
+            color: colors.textPrimary,
+            opacity: ctaS,
+            transform: `translateY(${interpolate(ctaS, [0, 1], [30, 0])}px)`,
+          }}
+        >
+          STORE CTA LINE
+        </div>
+        <div
+          style={{
+            fontFamily: fonts.body,
+            fontWeight: 400,
+            fontSize: 30,
+            color: colors.textSecondary,
+            opacity: subS,
+            transform: `translateY(${interpolate(subS, [0, 1], [24, 0])}px)`,
+          }}
+        >
+          OUTRO SUBTITLE
+        </div>
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+// User-provided music bed (public/audio/bgm.mp3). Keep null when absent —
+// never source or download music for the user (licensing is theirs).
+const BGM: string | null = null;
+
+export const Promo: React.FC = () => {
+  const timing = linearTiming({durationInFrames: TRANSITION_FRAMES});
+  return (
+    <>
+      {BGM ? (
+        <Audio
+          src={staticFile(BGM)}
+          volume={(f) =>
+            interpolate(f, [TOTAL_DURATION - 30, TOTAL_DURATION], [1, 0], {
+              extrapolateLeft: 'clamp',
+            })
+          }
+        />
+      ) : null}
+    <TransitionSeries>
+      <TransitionSeries.Sequence durationInFrames={DURATIONS.intro}>
+        <IntroScene />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition presentation={fade()} timing={timing} />
+
+      <TransitionSeries.Sequence durationInFrames={DURATIONS.feature1}>
+        <FeatureScene
+          watermark="FEATURE WORD"
+          eyebrow="EYEBROW"
+          headline="HEADLINE"
+          body="One-sentence body copy."
+          screenshot="01-feature.png"
+          enterFrom="bottom"
+          tiltY={-6}
+        />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition
+        presentation={slide({direction: 'from-right'})}
+        timing={timing}
+      />
+
+      <TransitionSeries.Sequence durationInFrames={DURATIONS.feature2}>
+        <FeatureScene
+          watermark="FEATURE WORD"
+          eyebrow="EYEBROW"
+          headline="HEADLINE"
+          body="One-sentence body copy."
+          screenshot="02-feature.png"
+          enterFrom="right"
+          tiltY={6}
+        />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition
+        presentation={slide({direction: 'from-left'})}
+        timing={timing}
+      />
+
+      <TransitionSeries.Sequence durationInFrames={DURATIONS.feature3}>
+        <FeatureScene
+          watermark="FEATURE WORD"
+          eyebrow="EYEBROW"
+          headline="HEADLINE"
+          body="One-sentence body copy."
+          screenshot="03-feature.png"
+          enterFrom="left"
+          tiltY={-6}
+        />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition presentation={fade()} timing={timing} />
+
+      <TransitionSeries.Sequence durationInFrames={DURATIONS.feature4}>
+        <FeatureScene
+          watermark="FEATURE WORD"
+          eyebrow="EYEBROW"
+          headline="HEADLINE"
+          body="One-sentence body copy."
+          screenshot="04-feature.png"
+          enterFrom="bottom"
+          tiltY={-6}
+          glow
+        />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition presentation={fade()} timing={timing} />
+
+      <TransitionSeries.Sequence durationInFrames={DURATIONS.outro}>
+        <OutroScene />
+      </TransitionSeries.Sequence>
+    </TransitionSeries>
+    </>
+  );
+};

package/assets/skills/promo-video/assets/theme.template.ts

@@ -0,0 +1,27 @@
+// Token bridge: map the app's design tokens 1:1 — never invent values.
+// Replace font families and hex values with the app's own (e.g. lib/theme.ts).
+import {loadFont as loadDisplay} from '@remotion/google-fonts/Oswald';
+import {loadFont as loadBody} from '@remotion/google-fonts/Inter';
+
+const display = loadDisplay('normal', {weights: ['600', '700']});
+const body = loadBody('normal', {weights: ['400', '500', '600']});
+
+export const fonts = {
+  display: display.fontFamily,
+  body: body.fontFamily,
+};
+
+export const colors = {
+  bg: '#0A0A0B',
+  surface: '#17171A',
+  panel: '#212126',
+  border: '#26262B',
+  borderStrong: '#3F3F46',
+  accent: '#DC2626',
+  textPrimary: '#FAFAFA',
+  textSecondary: '#A1A1AA',
+  textMuted: '#71717A',
+};
+
+// Shared radial backdrop: surface center fading to near-black edges.
+export const radialBackground = `radial-gradient(ellipse at center, ${colors.surface} 0%, ${colors.bg} 70%)`;

package/assets/skills/promo-video/references/pipeline.md

@@ -0,0 +1,119 @@
+# Promo Video Pipeline — Runbook
+
+Verified end-to-end on a real run (Expo SDK 57 monorepo, Remotion 4.0.496, macOS).
+
+## §1 Prerequisites
+
+- Node 18+; network access (google-fonts packages fetch font files at render time).
+- Inputs inventory before scaffolding:
+  - App token file (colors, font roles) — e.g. `apps/mobile/lib/theme.ts`.
+  - Transparent logo PNG at high resolution (e.g. `docs/logo/mark-transparent-3072.png`).
+  - Store screenshots (e.g. `store/screenshots/ios/iphone-6.9/*.png`) — record their pixel size; the device-frame aspect ratio derives from it (e.g. 1320/2868).
+  - Store copy + locale (`store/store.config.json` title/subtitle/promoText) — on-screen copy must match the listing's language and claims.
+
+## §2 Project setup
+
+- Scaffold `tools/promo/` from `assets/package.template.json`. CRITICAL: this path must be OUTSIDE the monorepo's npm `workspaces` globs (`apps/*`, `packages/*`) so it keeps its own `node_modules` — Remotion needs react-dom and a hoisted install will fight the app's React (Expo/RN).
+- Pin all Remotion packages (`remotion`, `@remotion/cli`, `@remotion/google-fonts`, `@remotion/transitions`) to the SAME exact 4.x version; react/react-dom 19.
+- `npm install` inside `tools/promo` (non-interactive).
+- Minimal source layout: `src/index.ts` (registerRoot), `src/Root.tsx` (one `<Composition id="Promo">`, 1080×1920@30), `src/theme.ts`, `src/Promo.tsx`. Boilerplate for index/Root:
+
+```tsx
+// src/index.ts
+import {registerRoot} from 'remotion';
+import {Root} from './Root';
+registerRoot(Root);
+
+// src/Root.tsx
+import {Composition} from 'remotion';
+import {Promo, TOTAL_DURATION} from './Promo';
+export const Root = () => (
+  <Composition id="Promo" component={Promo} durationInFrames={TOTAL_DURATION}
+    fps={30} width={1080} height={1920} />
+);
+```
+
+- Copy logo + selected screenshots into `tools/promo/public/`; reference ONLY via `staticFile()`. Skip visually weak screenshots (login screens rarely earn a scene).
+- Add root script `"promo:render": "cd tools/promo && npx remotion render Promo out/promo.mp4"` — the explicit `cd` forces the directory context so the render always resolves `tools/promo`'s own `node_modules` (`npm --prefix` also works, but the `cd` form is unambiguous); gitignore `tools/promo/out/`.
+
+## §3 Brand mapping
+
+- Map the app tokens 1:1 into `src/theme.ts` (see `assets/theme.template.ts`): background, surface, border, accent, three text tiers. Never invent values.
+- Fonts via `@remotion/google-fonts/<Family>` `loadFont()` — load only the weights used. Respect the app's typography roles (e.g. condensed display face always uppercase with letter-spacing; body face for sentences).
+- Shared backdrop: radial gradient, surface color at center fading to background at ~70% — reads premium, avoids flat black.
+
+## §4 Scene direction system
+
+The default 25s structure (six scenes): intro lockup → 3–4 feature scenes → outro. All animation via `spring()` (damping 14–18); nothing linear except slow drifts. Scene-to-scene via `@remotion/transitions` `TransitionSeries` (fade or slide, ~12 frames).
+
+- **Intro**: logo springs in (scale 0.7→1 + opacity), wordmark rises from below, accent bar wipes (scaleX, origin left), eyebrow line above in secondary text.
+- **Feature scene template** (see `assets/promo.template.tsx`):
+  - Giant watermark word behind everything: display font ~340px uppercase, `color: transparent` + `WebkitTextStroke 1px rgba(250,250,250,0.05)`, partially off-canvas, drifting a few px across the scene.
+  - Device frame built in CSS: rounded ~64px, ~10px bezel border, overflow hidden, `boxShadow 0 40px 80px rgba(0,0,0,0.6)`, perspective 1200px with rotateY tilt that springs from ±6° to ~25% residual (never fully flat — keeps depth), slow ±8px sine float.
+  - Phone enters springing from bottom/left/right — alternate direction and tilt sign per scene for variety.
+  - Copy block: eyebrow (accent color, letter-spaced uppercase) → headline (display 700 ~72px) → body (body font, secondary color), staggered ~5 frames apart.
+  - Accent moment: one scene gets a one-shot radial glow pulse behind the device (accent color at 0.25 alpha, opacity up-then-down).
+- **Outro**: lockup again at higher speed, then CTA line ("Disponible en el App Store" / locale equivalent), then one subtitle. Hold ≥1.5s fully settled at the end.
+
+### Audio bed
+
+Use a user-provided `public/audio/bgm.mp3`, or source one ONLY on explicit user request — never silently.
+
+Sourcing protocol (verified):
+- Use a library whose license allows commercial use without attribution: Mixkit Stock Music Free License (works well — tag pages at `mixkit.co/free-stock-music/tag/<tag>/` embed JSON-LD with name/genre/duration/direct mp3 URL, scrapeable with curl + a browser UA). Pixabay's license also qualifies but the site 403-blocks non-browser fetching — don't burn time there.
+- Derive search tags from the brand vibe, not generic terms: athletic/martial dark brand → `trailer`, `sports`, `percussion`, `epic`; playful consumer app → `upbeat`, `funk`, `pop`. Prefer instrumental "Percussion Trailer" / "Trailer Music" genres for dark athletic brands — no melodic identity to clash with the copy.
+- You cannot listen: say so, pick by genre/tags/duration, and note the user judges with one listen (swapping the file re-renders in minutes).
+- Record source URL + license in a comment directly above the `<Audio>` element.
+- Track longer than the video is fine — playback cuts at composition end; the fade-out handles the exit.
+
+Render it as a SIBLING of the `TransitionSeries` (`<Audio>` is not a wrapper):
+
+```tsx
+<>
+  <Audio
+    src={staticFile('audio/bgm.mp3')}
+    volume={(f) =>
+      interpolate(f, [TOTAL_DURATION - 30, TOTAL_DURATION], [1, 0], {
+        extrapolateLeft: 'clamp',
+      })
+    }
+  />
+  <TransitionSeries>…</TransitionSeries>
+</>
+```
+
+The 30-frame fade-out prevents a hard audio cut; the export is then social-ready with no post-production.
+
+### Non-vertical source screenshots
+
+Tablet (4:3) or horizontal screenshots must NEVER be stretched into the 9:16 canvas. Two accepted routes: (a) constrain the capture inside a fixed mobile mockup frame at its true aspect; (b) blurred-background fill — the same image scaled to cover the canvas with `filter: blur(40px)` + a dark overlay behind the true-aspect foreground copy.
+
+## §5 Timeline math
+
+`TransitionSeries` transitions OVERLAP scenes: total = Σ(scene durations) − Σ(transition frames). Example that lands exactly on 750 frames / 25s @30fps with five 12-frame transitions: 110 + 145 + 145 + 145 + 130 + 135 − 60 = 750. Export `TOTAL_DURATION` computed from the durations object — never hardcode the total.
+
+## §6 Render + verify
+
+- Render from `tools/promo`: `npx remotion render Promo out/promo.mp4` — ALWAYS foreground. A render started with a backgrounded process inside a sub-agent dies when that agent's session ends; whoever owns the render waits for it.
+- Verify: Remotion bundles ffprobe (`node_modules/.bin` or via `npx remotion versions`) — check h264, expected WxH, fps, duration. System ffprobe is often absent; don't assume it.
+- Spot-check at least two frames visually: `npx remotion still Promo out/frame.png --frame=<n>` (pick a mid-feature frame and the outro) and view them.
+- Deliver the MP4 with duration/size and the marketing-vs-App-Preview note.
+
+## §7 Video-clip variant (instead of stills)
+
+- Record the simulator during a Maestro tour flow: `xcrun simctl io booted recordVideo clip.mov` (Ctrl-C to stop), one clip per feature.
+- Trim/normalize with ffmpeg if needed; place clips in `public/`; swap `<Img>` for `<OffthreadVideo src={staticFile('clip.mp4')} muted>` inside the same device frame. `OffthreadVideo` is the render-safe choice (frame-accurate, no HTMLVideoElement flakiness).
+- Keep clips short (3–4s per scene) and trim dead frames at the start.
+
+## §8 Troubleshooting
+
+| Symptom | Cause / Fix |
+|---|---|
+| Peer/type conflicts on install | Project got hoisted into workspaces — move outside globs; own lockfile |
+| Fonts render as system sans | `loadFont()` not called at module scope, or offline — google-fonts needs network at render |
+| Render "completes" but no file | Render was backgrounded and its owner session ended — re-run foreground |
+| Total duration off by N frames | Forgot transition overlap subtraction — §5 |
+| Screenshot distorted in frame | Frame aspect must derive from the real screenshot pixel ratio, `objectFit: cover` |
+| Tablet/horizontal screenshots in a 9:16 comp | Never stretch — mockup-frame constrain or blurred-background fill (§4) |
+| No audio in exported MP4 | `<Audio>` missing or rendered inside a Sequence that ends early — mount it at composition top level (§4) |
+| Studio port busy | `npx remotion studio --port <other>` |

package/assets/skills/promo-video-web/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: promo-video-web
+description: Trigger: webapp promo, dashboard promo, web promo video, promo del dashboard, promo de la web, landing video, product demo video. Generate branded promotional MP4s for web surfaces (web app, admin dashboard) with Remotion + Playwright captures.
+---
+
+# Promo Video — Web Surfaces
+
+## Activation Contract
+
+Activate when a web surface — the product web app (`apps/web`) or the admin dashboard (`apps/dashboard`) — needs a promotional/marketing video. Each surface gets its OWN composition and MP4 (different audience, different register). Mobile app promos belong to `promo-video`.
+
+## Hard Rules
+
+- Same isolation rule as `promo-video`: the Remotion project lives at `tools/promo/` OUTSIDE npm workspaces. If `tools/promo/` already exists (mobile promo), ADD compositions to it — never create a second Remotion project.
+- Captures come from the REAL running app via Playwright against seeded demo data — never mockups. Fixed viewport 1920×1080, `deviceScaleFactor: 2` (crisp 2x assets). Dashboard captures log in with demo credentials injected via env vars — never hardcoded in the capture script.
+- Capture stability is a gate: `headless: true` strictly enforced (the agent must never hang waiting for a GUI in terminal environments), and every capture waits for `networkidle` PLUS explicit unmount of spinners/skeletons PLUS a real-data selector — a capture showing a loading state is a quality failure.
+- Brand fidelity: colors/fonts from the surface's own token source (web CSS vars / tailwind theme); copy from the product definition — never invent claims.
+- Register per surface: web app = product marketing (benefit-led copy); dashboard = operator tool (calm, outcome-led copy: "manage X in seconds", no hype). A dashboard promo that reads like a consumer ad is a quality failure.
+- Landscape 1080p (1920×1080@30) default for web surfaces; vertical only on explicit request.
+- On-screen copy in the product's locale; code and comments in English.
+- Foreground renders only; TransitionSeries timeline math (total = Σ durations − Σ overlaps) — same as `promo-video`.
+
+## Decision Gates
+
+| Situation | Route |
+|---|---|
+| Which surface | One composition per surface: `PromoWeb`, `PromoDashboard` — separate MP4s, separate copy registers |
+| `tools/promo/` exists | Add `src/web/` sources + compositions + `render:web` / `render:dashboard` scripts; add `playwright` devDep |
+| Motion instead of stills | Playwright `recordVideo` context while scripting the flow; embed via `<OffthreadVideo>` |
+| App not deployed / no local stack | Capture against the local dev server with seeded data; block only if neither runs |
+| Multiple surfaces share scene code | Drive COLOR tokens via `getInputProps()` + `--props=./<surface>-tokens.json` at render time instead of rewriting `theme.ts` per run; fonts stay code-level (`loadFont()` runs at module scope and cannot come from JSON) |
+
+## Execution Steps
+
+1. Read `references/pipeline.md`. Inventory: surface URL (local or deployed), demo credentials (env), token source, product copy, locale.
+2. Seed a PREDICTABLE, isolated demo state first — on multi-tenant products, pass an explicit test-tenant ID via env (`PROMO_TENANT`) so captures never show empty states or another tenant's data.
+3. Capture: adapt `assets/capture.template.ts`; run it (foreground, headless) to produce `public/web/*.png` (or clips) — authenticate, wait for the state to hydrate (spinners/skeletons unmounted, real-data selector present), then snap. Login flow for the dashboard, key screens per surface, 4–6 captures.
+4. Scaffold or extend `tools/promo/` per the Decision Gates; map web tokens into a surface theme file (or per-surface `--props` token JSON — Decision Gates).
+5. Build scenes on `assets/browser-promo.template.tsx`: intro lockup → 3–4 feature scenes (browser-chrome-framed capture with slow Ken Burns zoom, split copy layout) → CTA outro with the surface URL.
+6. Render each composition foreground (`npx remotion render PromoWeb out/promo-web.mp4`, same for dashboard); add root scripts (cd form, per `promo-video`); verify duration/fps + `remotion still` spot-checks; deliver MP4s.
+
+## Output Contract
+
+Return: MP4 path(s) with duration/fps/size, capture inventory, files created, root scripts added, and which register was applied per surface.
+
+## References
+
+- `references/pipeline.md` — capture protocol, browser-frame scene system, per-surface registers, multi-composition layout, troubleshooting.
+- `assets/capture.template.ts` — Playwright capture script (viewport, auth via env, screenshot set).
+- `assets/browser-promo.template.tsx` — landscape scene architecture: browser chrome frame, Ken Burns, split copy layout, CTA outro.
+- `assets/package.template.json` — deps when scaffolding fresh (Remotion pinned + playwright).