Feature Implementation Workflow

Overview

This skill provides a structured, safe workflow for designing and implementing new features in Clypra. Clypra is a multi-tier desktop application (React 19 + Tauri 2.x + Rust wgpu compositor). Uncontrolled feature additions can easily violate data-flow invariants, cause playhead jitter, or introduce IPC performance regressions.

When to Use This Skill

• Implementing a new user-facing tool, panel, or modal.
• Adding a new clip type, transition, or effect.
• Extending timeline operations or export preset options.
• Integrating a new native backend capability or IPC command.

When NOT to Use This Skill

• Fixing an existing bug or regression (use bugfix-regression).
• Reviewing existing PRs or commits (use code-review).
• Preparing a release candidate (use release-readiness).

Step-by-Step Procedure

1. Clarify Scope and Acceptance Criteria

• Explicitly state what the feature will do and what is out of scope.
• Identify the target user interaction model and performance requirements.
• Identify whether the feature touches the preview render path, timeline state, or native engine.

2. Inspect Existing Architecture & Patterns

• Check AGENTS.md and .agents/rules/architecture.md for governing constraints.
• Consult .agents/skills/clypra-dev/SKILL.md Section 21 (Quick Subsystem Decision Guide).
• Inspect similar features already implemented in src/features/ or src/core/.
• Never create a duplicate store, secondary playback clock, or parallel evaluation path.

3. Identify Subsystem Boundaries & Compute Tier

Determine where each component belongs based on the Three-Layer Rule:

• Tier 1 (Main/React): UI layout, user input, dialogs, Zustand action triggers.
• Tier 2 (Web Worker): Complex data transformations (>2ms), geometry calculations, curve evaluation.
• Tier 3 (Rust Native): GPU shaders, video decoding, audio synthesis, disk I/O, IPC handlers.

4. Plan Proportional Implementation & Test Strategy

• Propose the smallest coherent change to achieve the feature.
• Plan unit tests for pure domain functions before touching state or UI.
• If timeline mutations are involved, implement them as commands in src/core/commands/ so they support undo/redo via historyStore.
• If new types are needed, define them in src/types/ and ensure backward compatibility.

5. Incremental Implementation

• Step 1: Types & Core Engine logic (pure TypeScript functions).
• Step 2: Zustand Store actions (if new state is required; ensure persistence rules are respected).
• Step 3: UI Components (using Clypra design tokens and Radix/Tailwind primitives).
• Step 4: IPC bridge handlers (if native functionality is needed, ensure path validation via security.rs).

6. Mandatory Mixed-Stack Benchmark, Scalability & Deep Automation Contract

Every new feature, clip type, layer capability, or subsystem upgrade must execute an automated deep verification pass to guarantee performance, latency, scalability, and cross-subsystem stability before declaring completion. This rigorous automation suite eliminates regressions and makes manual testing optional.

┌────────────────────────────────────────────────────────────────────────────────────────┐
│               MANDATORY DEEP AUTOMATION & BENCHMARK SUITE CONTRACT                     │
├──────────────────────────┬──────────────────────────┬──────────────────────────────────┤
│ 1. Mixed-Stack Benchmarks│ 2. Scale & Concurrency   │ 3. Interference & Root Cause     │
│ Video + Music + Text +   │ Evaluate 1, 10, 50, 100+ │ Verify Audio CPAL, Preview Clock,│
│ Stickers in unison       │ concurrent instances     │ Native Presenter, GC pauses      │
├──────────────────────────┼──────────────────────────┼──────────────────────────────────┤
│ 4. Telemetry Recording   │ 5. Deep Pixel Oracles    │ 6. State & Fuzzing Oracles       │
│ Hooks to telemetry       │ PSNR ≥ 60dB / MSE ≤0.0001│ Rapid undo/redo, transaction     │
│ collector & NDJSON logs  │ golden-frame pixel diffs │ fuzzing, atomic persistence      │
└──────────────────────────┴──────────────────────────┴──────────────────────────────────┘

Requirement A: Multi-Property Mixed-Stack Benchmark Harness

• Never evaluate features in isolation: Benchmarking a new feature alone (e.g., testing only stickers or only text) masks real-world contention.
• Mandatory Mixed Workload: All performance benchmarks must evaluate the feature within a realistic production composition combining:
  1. Video: 4K/1080p HEVC or H.264 primary background playback.
  2. Audio / Music: Multi-track stereo/mono audio with active volume keyframe rubber bands.
  3. Text & Titles: Dynamic text layers with active typography/effects.
  4. Stickers & Visual Overlays: Vector Lottie or raster overlays with transforms. (Reference standard: src/benchmarks/goldenProjectManifest.ts and src/lib/export/__tests__/mixedStackExportParity.test.ts).

Requirement B: High-Concurrency Scalability Stress ($1 \to 10 \to 50 \to 100+$ instances)

• Multi-Instance Scaling Analysis: Measure throughput and latency curves across 4 concurrency tiers:
  • 1 instance: Baseline overhead.
  • 10 instances: Typical production scene density.
  • 50 instances: Complex composite scene.
  • 100+ instances: Extreme stress / worst-case saturation boundary.
• Required Metrics to Record:
  • Latency Distribution: Frame render duration p50, p95, and max ($\text{ms}$).
  • Frame Pacing: Pacing variance and dropped-frame count against 60fps ($16.6\text{ms}$ budget).
  • Memory Footprint: Heap delta ($\Delta \text{MB}$) and GPU texture allocation over sustained loops (e.g. 5-minute / 9,000-frame simulation).
  • Throughput: Maximum sustained frames rendered per second (FPS).

Requirement C: Cross-Subsystem Interference & Root-Cause Explanation ("The Why")

When running under high concurrency (e.g., 50–100+ instances), the agent must explicitly verify and explain the impact on neighboring subsystems:

1. Audio Engine Stability (CPAL / rtrb / wsola):
   • Does high layer density starve the real-time audio callback thread ($< 5.3\text{ms}$ buffer budget at $48\text{kHz}$)?
   • Verify zero buffer underruns, zero audible clicks, and zero AV desynchronization or drift.
2. Video Decoder & Playhead Authority (PlaybackClock.ts):
   • Does layer rasterization or compositing block the main event loop, causing seek stutter or clock desynchronization?
   • Verify that PlaybackClock.ts remains the uncompromised single time authority (Architecture Invariant 1).
3. Compositor & Presenter Selection:
   • Does layer overhead cause the native GPU presenter (Metal/DirectX) to bail out or fall back to DOM/WebGL canvas readbacks (sticker-or-raster-unsupported)?
   • Verify that the native preview hardware surface remains active unless explicitly unsupported.
4. Main Thread Event Loop & V8 Garbage Collection:
   • Do per-frame object or buffer allocations trigger V8 Major GC pauses ($> 16\text{ms}$ jank)?
5. Root-Cause Analysis ("Why is it fast or slow?"):
   • If performance scales sub-linearly or degrades under stress, document the physical constraint (e.g. CPU Web Worker IPC serialization cost, GPU memory bandwidth/fill rate, main-thread layout thrashing, or texture cache misses) and implement the appropriate mitigation (instancing, memory pooling, Worker offloading).

Requirement D: Production Telemetry Instrumentation

• Every new capability, layer type, or pipeline stage must instrument telemetry:
  • Register with telemetryCollector to record metrics into Clypra's append-only NDJSON session logs (perf_logs/).
  • Track: execution duration per frame, cache hit/miss ratio, GPU texture allocations, and fallback occurrences.
  • Automated tests must assert that telemetry events are correctly emitted with appropriate tags and payload shapes.

Requirement E: Deep Mathematical & Behavioral Verification Oracles (Zero-Manual QA)

Manual clicking cannot detect subtle sub-pixel drift, color banding, or audio phase corruption. Automated mathematical oracles are mandatory:

1. Golden-Frame Pixel Oracles:
   • Utilize computePixelDiff() from src/lib/renderEngine/pixelDiff.ts.
   • Compare Preview vs. Export renders across multiple sampled timestamps ($t = 0, 0.25d, 0.5d, 0.75d, d$).
   • Enforce Peak Signal-to-Noise Ratio $\text{PSNR} \ge 60\text{ dB}$ (or $\infty\text{ dB}$ for exact matches), Mean Squared Error $\text{MSE} \le 0.0001$, and 0 unexplained differing pixels.
2. Audible Signal & RMS Oracles:
   • Verify audio processing using physical CoreAudio/CPAL test harnesses or RMS energy assertions to ensure non-zero, non-clipped, drift-free output.
3. Timeline State & Command Fuzzing:
   • Verify transactional mutations via historyStore.dispatch(command) under rapid undo/redo cycles, edge-case boundary trimming (t=0, t=clipEnd), and atomic project save/reopen fidelity.

7. Verify Local Quality Gates

Run the canonical verification suite:

# Ensure strict type safety
npx tsc --noEmit

# Run unit and integration tests for new/affected code
npx vitest run <path/to/feature.test.ts>

# Run core preview render loop regression suite
npx vitest run src/components/editor/preview/__tests__/ProgramPreview.renderLoop.test.ts

# Run Rust tests if native code was changed
cargo test --manifest-path src-tauri/Cargo.toml

# Run internationalization catalog parity
npm run i18n:check

# Subsystem contract suites (mandatory for preview/playback/audio/text changes)
# See AGENTS.md Section 6, Item 8
npx vitest run src/core/playback/__tests__/replayBehavioralContract.test.ts
npx vitest run src/core/audio/__tests__/audioPreviewSyncContract.test.ts
npx vitest run src/components/editor/preview/__tests__/previewStateResetContract.test.ts
npx vitest run src/features/text-effects/__tests__/textEditPreviewCycle.test.ts

# Canvas pixel validation (Layer A — browser rasterization)
npx playwright test tests/e2e/preview-canvas-pixel-validation.spec.ts

8. Inspect Diff & Report Completion

• Run git diff to confirm zero unrelated changes, temporary debug logs, or commented-out code.
• Report:
  • Exact files created or modified.
  • Behavior implemented and verified across multi-property workloads.
  • Benchmark & scalability results (p50/p95 latency, 1 vs 10 vs 50 vs 100 instances, memory stability, interference analysis).
  • Deep verification oracle results (PSNR/MSE pixel diffs, audio RMS, undo/redo fuzzing).
  • Telemetry instrumentation added.