@muskanmeet/invoicing-design-system 0.1.0

package/.local/skills/video-js/references/audio.md

@@ -0,0 +1,237 @@
+# Video Audio
+
+This reference is only available when audio generation callbacks are enabled. Use it during the main-agent post-build pass for `video-js` artifacts, after the DESIGN subagent has finished and workflow logs are clean.
+
+## Default behavior
+
+Generate exactly one default audio layer: instrumental background music. Do not generate voiceover, text-to-speech, or sound effects unless the user explicitly requested them.
+
+Skip default music only when the user explicitly asks for no music, no audio, silent playback, or a silent autoplay loop.
+
+## Generate background music
+
+1. Read `SCENE_DURATIONS` from `src/components/video/VideoTemplate.tsx`.
+2. Compute `totalRuntimeSeconds = Math.ceil(sum(Object.values(SCENE_DURATIONS)) / 1000)`.
+3. Generate music with the `generateMusic` callback and save it under the artifact's public audio directory:
+
+```javascript
+const music = await generateMusic({
+  prompt: "<style> instrumental background music scoring a <video type>. <instruments>, <BPM>, <mood>. Patient intro, steady build, a clear lift around the <keystone second>-second mark, resolved ending. No vocals, no harsh highs.",
+  outputPath: "artifacts/<slug>/public/audio/bg_music.mp3",
+  summary: "background music",
+  durationSeconds: totalRuntimeSeconds,
+  forceInstrumental: true,
+  outputFormat: "mp3_44100_128",
+  overwrite: true,
+});
+console.log(music.filePath);
+```
+
+Pick the music style intentionally:
+
+| Style | Use for |
+| --- | --- |
+| Driving electronic / synthwave, 110-128 BPM | Tech product reveals, developer tools, hardware, gaming, future-facing launches |
+| Lo-fi hip hop, 80-95 BPM | Creator tools, productivity apps, indie launches, warm human products |
+| Cinematic uplifting orchestral, 80-110 BPM | Brand films, mission-driven products, fintech, healthcare, founder stories |
+| Corporate motivational, 95-115 BPM | B2B SaaS, enterprise sales pieces, customer testimonials |
+| Cinematic minimal piano, 60-90 BPM | Luxury, editorial, premium hardware, fashion |
+| Ambient atmospheric, 60-90 BPM | AI/research-heavy content, calm utilities, thoughtful tech |
+| Funk / nu-disco, 105-115 BPM | Playful brands, design tools, social apps, confident upbeat launches |
+
+Always include `No vocals`. Sung lyrics fight voiceover and on-screen copy.
+
+## Add audio controls before playback wiring
+
+When applying `scene_selectors.md`, extend the control wrapper before adding the `<audio>` element to `VideoTemplate`.
+
+In `VideoWithControls`:
+
+- Add `const [muted, setMuted] = useState(true);` in the iframe branch.
+- Pass `muted={muted}` to `VideoTemplate`.
+- Add a `Volume2` / `VolumeX` toggle button next to the scene-lock button.
+- Keep the export path as `<VideoTemplate />` with no props, so export audio defaults to unmuted and the control bar stays hidden.
+
+Control bar order should be: scene-lock button, audio mute button, divider, segmented progress bar, scene counter, collapse chevron.
+
+Use declarative JSX for muting:
+
+```tsx
+<audio muted={muted} />
+```
+
+Do not set `audio.muted = muted` in an effect. That races browser autoplay in iframes and can make the first unmute click appear broken.
+
+## Wire time-synced playback
+
+Update `VideoTemplate` to accept `muted = false` while preserving existing defaults:
+
+```tsx
+export default function VideoTemplate({
+  durations = SCENE_DURATIONS,
+  loop = true,
+  muted = false,
+  onSceneChange,
+}: {
+  durations?: Record<string, number>;
+  loop?: boolean;
+  muted?: boolean;
+  onSceneChange?: (sceneKey: string) => void;
+} = {}) {
+  const { currentScene, currentSceneKey } = useVideoPlayer({ durations, loop });
+  // ...
+}
+```
+
+Derive scene offsets from the canonical durations:
+
+```tsx
+const SCENE_START_SEC: Record<string, number> = (() => {
+  const out: Record<string, number> = {};
+  let cumulativeMs = 0;
+  for (const [key, ms] of Object.entries(SCENE_DURATIONS)) {
+    out[key] = cumulativeMs / 1000;
+    cumulativeMs += ms;
+  }
+  return out;
+})();
+```
+
+Then add one music element and seek it on scene changes:
+
+```tsx
+const AUDIO_SEEK_EPSILON_SEC = 0.18;
+const audioRef = useRef<HTMLAudioElement | null>(null);
+const baseSceneKey = currentSceneKey.replace(/_r[12]$/, '');
+
+useEffect(() => {
+  const audio = audioRef.current;
+  if (!audio) return;
+  audio.volume = 0.45;
+  const targetTime = SCENE_START_SEC[baseSceneKey] ?? 0;
+  if (Math.abs(audio.currentTime - targetTime) > AUDIO_SEEK_EPSILON_SEC) {
+    audio.currentTime = targetTime;
+  }
+  audio.play().catch(() => {});
+}, [currentSceneKey, baseSceneKey, muted]);
+
+return (
+  <>
+    {/* scenes and persistent layers */}
+    <audio
+      ref={audioRef}
+      src={`${import.meta.env.BASE_URL}audio/bg_music.mp3`}
+      preload="auto"
+      autoPlay
+      muted={muted}
+    />
+  </>
+);
+```
+
+This keeps playback aligned for normal looping, scene jumps, and scene-lock `_r1` / `_r2` replays. Do not use `currentScene === 0` as the reset condition: scene jumps rotate the durations object, so the clicked scene remounts at index 0 even though its audio should start at that scene's canonical `SCENE_START_SEC` offset. The small seek epsilon avoids an audible pause on normal scene transitions when the audio is already close to the correct timestamp.
+
+Do not add a `loop` attribute to the audio element; `useVideoPlayer` owns loop timing and the effect resets audio at the visual loop boundary because the first canonical scene's offset is `0`.
+
+## Requested voiceover or SFX
+
+Only add these layers when the user asked for them.
+
+### Voiceover
+
+Use `searchVoices` first unless the user provided a voice ID, then generate TTS with `textToSpeech`.
+
+```javascript
+const voices = await searchVoices({ search: "warm narrator", pageSize: 5 });
+const voiceId = voices.voices[0].voice_id;
+const vo = await textToSpeech({
+  text: "Meet Nova. Redesigned from the ground up.",
+  voiceId,
+  outputPath: "artifacts/<slug>/public/audio/vo_intro.mp3",
+  summary: "intro voiceover",
+  modelId: "eleven_multilingual_v2",
+  voiceSettings: {
+    stability: 0.55,
+    similarity_boost: 0.75,
+    style: 0.35,
+    use_speaker_boost: true,
+  },
+  overwrite: true,
+});
+console.log(vo.filePath);
+```
+
+Voiceover should complement on-screen text, not read every word. Keep each line short enough to fit its scene with at least 400ms of tail buffer.
+
+### Sound effects
+
+Use `generateSoundEffect` sparingly. SFX should punctuate a specific beat, such as a logo reveal or hard scene cut. When in doubt, leave SFX out.
+
+```javascript
+const sfx = await generateSoundEffect({
+  prompt: "Soft futuristic logo reveal chime, clean, short, no reverb tail clutter",
+  outputPath: "artifacts/<slug>/public/audio/sfx_logo_reveal.mp3",
+  summary: "logo reveal chime",
+  durationSeconds: 1.2,
+  loop: false,
+  promptInfluence: 0.4,
+  overwrite: true,
+});
+console.log(sfx.filePath);
+```
+
+## Multi-layer export parity
+
+If the mix includes voiceover or SFX, pre-mix all layers into one `public/audio/composite_audio.mp3` with `ffmpeg` before wiring playback. Per-scene `<audio src>` swaps can drift in recorded exports.
+
+Build the composite with cumulative scene-start offsets:
+
+```javascript
+const inputs = ['public/audio/bg_music.mp3'];
+const filters = ['[0:a]volume=0.24[m]'];
+const mixLabels = ['[m]'];
+let inputIdx = 1;
+let cumulativeMs = 0;
+
+for (const scene of SCENES) {
+  if (scene.voiceoverFile) {
+    const delay = cumulativeMs + (scene.voiceoverDelayMs ?? 250);
+    inputs.push(`public/audio/${scene.voiceoverFile}`);
+    filters.push(`[${inputIdx}:a]volume=1.0,adelay=${delay}|${delay}[vo${scene.key}]`);
+    mixLabels.push(`[vo${scene.key}]`);
+    inputIdx++;
+  }
+  if (scene.sfxFile) {
+    inputs.push(`public/audio/${scene.sfxFile}`);
+    filters.push(`[${inputIdx}:a]volume=0.45,adelay=${cumulativeMs}|${cumulativeMs}[sfx${scene.key}]`);
+    mixLabels.push(`[sfx${scene.key}]`);
+    inputIdx++;
+  }
+  cumulativeMs += scene.ms;
+}
+
+const filterComplex =
+  filters.join(';') +
+  `;${mixLabels.join('')}amix=inputs=${mixLabels.length}:duration=longest:dropout_transition=0:normalize=0[out]`;
+```
+
+Critical details:
+
+- Use `adelay=N|N` so both stereo channels are delayed.
+- Use `normalize=0` so the volume filters are respected.
+- Clamp output to the total video runtime with `-t <totalSeconds>`.
+- Use `composite_audio.mp3` in `VideoTemplate` instead of `bg_music.mp3` when a composite exists.
+- With voiceover, duck background music to `0.18-0.28`; without voiceover, keep music around `0.40-0.55`.
+
+## Checklist
+
+- [ ] Default audio is exactly one instrumental background music file unless the user requested more.
+- [ ] Music duration matches `SCENE_DURATIONS` total runtime.
+- [ ] Audio files live in `public/audio/`.
+- [ ] Public audio paths use `${import.meta.env.BASE_URL}audio/...`.
+- [ ] Iframe preview defaults to muted and exposes a `Volume2` / `VolumeX` control.
+- [ ] Export path renders `<VideoTemplate />` with no props, so audio is unmuted and controls are hidden.
+- [ ] The `<audio>` element uses declarative `muted={muted}`.
+- [ ] `audio.play()` is wrapped in `.catch(() => {})`.
+- [ ] Scene jumps, scene-lock loops, and full-video loops keep audio aligned with the visible scene.
+- [ ] Requested VO/SFX layers are pre-mixed into `composite_audio.mp3` for export parity.

package/.local/skills/video-js/references/finalize_playback.md

@@ -0,0 +1,16 @@
+# Video Finalization -- Polish & Frame Integrity
+
+You are a subagent responsible for polishing the video after the main agent has finished all creative work.
+
+**Your job:** Verify that all content fits within the 16:9 frame without cutoff, and ensure the video loops cleanly. Do not modify any creative content -- animations, colors, fonts, motion timing, visual direction, scene durations, or scene count are off limits.
+
+## Principles
+
+- **Scale, not reflow.** The video is a fixed 16:9 composition that should look identical at any viewport size, just smaller. Use viewport-relative units (`vw`, `vh`, `%`) for layout-critical dimensions. Do not introduce responsive breakpoints or conditional layouts.
+- **Frame containment.** The root container needs `overflow-hidden`. Large hardcoded pixel values for font sizes, positions, or element dimensions should be viewport-relative. Images and video clips need proper `object-fit` so they don't stretch or overflow.
+- **Loop integrity.** Every scene must have both enter and exit animations. Each scene inside `AnimatePresence` needs a unique `key`. No `useState` flags or conditions that could block scene advancement -- the video plays and loops forever.
+- **Recording lifecycle.** Do not edit `src/lib/video/hooks.ts`, remove `window.startRecording?.()` / `window.stopRecording?.()`, or remove `useVideoPlayer` from the main video entry. Export depends on those calls firing from the hook -- replacing it with local scene state, inlining a timer, or "simplifying" the lifecycle will break export even if the preview still loops.
+
+## Process
+
+Read `VideoTemplate.tsx` and every scene file before making changes. Walk through each file checking for frame containment issues and loop problems. Only make changes that fix overflow/cutoff or broken looping. If everything looks correct, report that no changes were needed.

package/.local/skills/video-js/references/first_build.md

@@ -0,0 +1,87 @@
+<first_build>
+When building a new animated video for the first time, follow this exact sequence. Do not deviate.
+
+## What the scaffold provides
+
+These files are already opened in your context after `createArtifact()` returns. Do NOT re-read them:
+
+- `src/components/video/VideoTemplate.tsx` -- template with placeholder ReplitLoadingScene, `useVideoPlayer` hook wired up
+- `src/lib/video/hooks.ts` -- `useVideoPlayer` and `useSceneTimer` hooks (DO NOT MODIFY -- recording/export depends on exact implementation)
+- `src/lib/video/animations.ts` -- 40+ animation presets (springs, easings, scene transitions, element animations, kinetic typography variants)
+- `src/lib/video/index.ts` -- barrel export of hooks and animations
+- `src/index.css` -- Tailwind imports + CSS variables for colors and fonts (subagent will customize)
+- `index.html` -- HTML shell with Google Fonts preloaded
+- `src/main.tsx` -- React entry point
+
+Pre-installed packages (do NOT install these): `framer-motion`, `gsap`, `@react-spring/web`, `three`, `@react-three/fiber`, `@react-three/drei`, `lucide-react`, `tailwindcss`, `clsx`, `tailwind-merge`, `lottie-react`.
+
+## Build sequence
+
+Execute these 5 steps in order. No additional steps.
+
+### Step 1: Delegate to DESIGN subagent
+
+Call `subagent()` (synchronous -- blocks until complete). Pass the user's request exactly as-is, prefixed with the skill reference. Do NOT add creative direction, color guidance, typography choices, or any other prescriptive instructions.
+
+```javascript
+const result = await subagent({
+    task: `You are the subagent executing this task, see the skill: .local/skills/video-js/SKILL.md\n\n${userRequest}`,
+    specialization: "DESIGN",
+    relevantFiles: [".local/skills/video-js/SKILL.md", ".local/skills/video-js/references/finalize_playback.md"]
+});
+```
+
+The design subagent handles the visual animation: creative direction, visual asset generation (images, video clips, stock photos), scene building, CSS theming, validation (`validate-recording.sh`), and finalization (frame containment, loop integrity). You do not verify or fix its output.
+
+
+Do not ask the design subagent to generate, plan, or wire audio by default. Background music, audio controls, and time-synced playback are main-agent post-build work after the design subagent returns.
+
+
+### Step 2: Restart the workflow
+
+```javascript
+await restart_workflow({ name: "artifacts/<slug>: web" });
+```
+
+### Step 3: Check logs for errors
+
+```javascript
+await refresh_all_logs();
+```
+
+Read the workflow logs. If there are build errors (missing imports, syntax errors, etc.), fix them and restart the workflow again. If the logs are clean, proceed to step 4.
+
+
+### Step 4: Generate default background music (main agent only -- do not delegate)
+
+After the design subagent has finished and workflow logs are clean, generate exactly one default background music bed with the `generateMusic` callback. Do not generate voiceover/TTS or SFX unless the user explicitly requested them.
+
+Follow `.local/skills/video-js/references/audio.md` exactly for music prompting, output paths, runtime matching, extra user-requested audio, and playback wiring. Generate the audio before editing the animation controls so you know which file path the player will use.
+
+### Step 5: Add scene controls, audio controls, and synced audio (main agent only -- do not delegate)
+
+After the default music has been generated, add the interactive control bar at the bottom of the video so the viewer can jump between scenes, toggle scene-lock, and mute/unmute preview audio. The bar renders only when the video is inside an iframe (the Replit preview pane). The exporter launches the video as the top-level document, so the gate hides the bar during export and the exported frame stays clean.
+
+Follow `.local/skills/video-js/references/scene_selectors.md` for the scene-control architecture. While making those edits, follow `.local/skills/video-js/references/audio.md` in this order:
+
+1. Add the audio controls to `VideoWithControls` and pass `muted` into `VideoTemplate`.
+2. Then wire the generated audio into `VideoTemplate` with scene-synced playback.
+3. Then run the final validation/restart/log/present sequence from `scene_selectors.md`.
+
+Do NOT delegate this step to any subagent. Do NOT add details about scene selectors or audio to any subagent task description. The design subagent must never be informed that scene selectors or default audio exist.
+
+`scene_selectors.md` owns the final workflow restart, log check, and `presentArtifact` call. Once that file's steps complete, the first build is done -- do NOT restart the workflow again and do NOT call `presentArtifact` a second time.
+
+
+## First build rules
+
+- Do NOT read any files before delegation to the design subagent -- scaffold files are documented above, and the subagent's output does not need verification.
+- Do NOT add your own creative direction, style instructions, color guidance, or typography choices to the subagent task. The design subagent is the creative expert -- let it make all decisions.
+- Do NOT use `startAsyncSubagent` -- use synchronous `subagent()` so you block until it's done.
+- Do NOT restart the workflow before the design subagent completes.
+- Do NOT take screenshots during the build.
+- Do NOT call `suggestDeploy()` -- video artifacts are not deployable. They are exported from the preview pane.
+- Do NOT delegate finalization separately -- the design subagent handles it per `<completing_your_run>` in the skill.
+- Do NOT delegate the audio or scene-selector step. The main agent runs both directly after the design subagent finishes. The design subagent must not be told about scene selectors or default audio.
+- There is no need to test or code review the first build beyond the scene-selector validation.
+</first_build>