> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# System architecture

> Understanding Helios's native-aligned architecture and design philosophy

Helios is built on a fundamentally different architecture than traditional programmatic video frameworks. Instead of simulating animation in JavaScript, Helios drives the browser's native animation engine.

## Core philosophy: native-aligned architecture

Most programmatic video frameworks treat the browser as a "screenshot machine"—they freeze time, inject frame numbers, calculate every interpolated value in JavaScript, and capture the result. This **simulation-based architecture** works, but it means reimplementing what the browser already does natively.

Helios takes a different approach: **drive the browser's animation engine, don't replace it.**

### The browser already knows how to animate

When you write CSS animations or use the Web Animations API, the browser's C++ rendering engine handles:

* Interpolation calculations
* Easing functions
* Hardware-accelerated compositing
* Subpixel rendering
* Performance optimizations

Helios leverages these native capabilities by controlling **time** rather than **values**.

<Tabs>
  <Tab title="Helios approach">
    ```css theme={null}
    /* Standard CSS - no changes needed */
    @keyframes fadeIn {
      from { opacity: 0; transform: scale(0.9); }
      to { opacity: 1; transform: scale(1); }
    }

    .element {
      animation: fadeIn 1s ease-out forwards;
    }
    ```

    ```typescript theme={null}
    // Helios controls time, browser handles animation
    helios.seek(45);
    // All CSS/WAAPI animations instantly update to frame 45
    ```
  </Tab>

  <Tab title="Simulation approach">
    ```typescript theme={null}
    // You calculate every value manually
    function MyComponent() {
      const frame = useCurrentFrame();
      const opacity = interpolate(frame, [0, 30], [0, 1]);
      const scale = interpolate(frame, [0, 30], [0.9, 1]);
      return <div style={{ opacity, transform: `scale(${scale})` }}>Hello</div>;
    }
    ```
  </Tab>
</Tabs>

## Dual-mode time control

Helios uses different time control mechanisms depending on the context:

### Production rendering: CDP virtual time

For server-side rendering in headless Chrome, Helios uses the **Chrome DevTools Protocol (CDP)** to virtualize time at the environment level.

```typescript theme={null}
// Simplified internal flow
await cdp.send('Emulation.setVirtualTimePolicy', {
  policy: 'advance',
  budget: 33.33  // Advance by exactly one frame (33.33ms at 30fps)
});
```

Key characteristics:

* **Deterministic**: The browser cannot advance until the frame is fully rendered
* **Scene-independent**: Render time is proportional to scene complexity
* **Native**: All CSS animations, WAAPI timelines, and `requestAnimationFrame` callbacks update automatically
* **Chromium-only**: Requires CDP access (headless Chrome/Chromium)

See `packages/renderer/src/drivers/CdpTimeDriver.ts:20` for implementation details.

### Preview mode: WAAPI seeking

For browser-based preview and development, Helios uses the **Web Animations API** to seek individual animations.

```typescript theme={null}
// Seek all animations to target time
document.getAnimations().forEach(anim => {
  anim.currentTime = targetTimeMs;
  anim.pause();
});
```

Key characteristics:

* **Interactive**: Works in any modern browser
* **Real-time**: No headless browser required
* **Standards-based**: Uses the writable `Animation.currentTime` property
* **Scrub-friendly**: Perfect for timeline scrubbing in the player

See `packages/core/src/drivers/DomDriver.ts:372` for implementation details.

<Note>
  The W3C spec marks `document.timeline.currentTime` as read-only, but individual `Animation` objects expose a writable `.currentTime` property. Helios uses this to seek animations without violating the spec.
</Note>

## Modular architecture

Helios is designed as a set of loosely-coupled packages:

```mermaid theme={null}
graph TD
    A[Core Engine] --> B[Renderer]
    A --> C[Player]
    A --> D[Studio]
    B --> E[CLI]
    D --> C
    
    style A fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333
    style C fill:#bfb,stroke:#333
    style D fill:#fbb,stroke:#333
    style E fill:#ffb,stroke:#333
```

### Core (`@helios-project/core`)

Headless logic engine with zero UI dependencies.

**Responsibilities:**

* Timeline state management (`currentFrame`, `duration`, `fps`)
* Playback controls (`play`, `pause`, `seek`)
* Signal-based reactivity
* Driver abstraction (TimeDriver, DomDriver, NoopDriver)
* Animation helpers (`interpolate`, `spring`, `sequence`)

**Key files:**

* `Helios.ts:79` - Main engine class
* `types.ts:11` - Configuration and state types
* `drivers/` - Driver implementations

### Renderer (`@helios-project/renderer`)

Server-side rendering pipeline using Playwright and FFmpeg.

**Responsibilities:**

* CDP-based time control
* Frame capture (screenshots or canvas)
* Video encoding pipeline
* Distributed rendering orchestration

**Key files:**

* `Renderer.ts` - Main rendering coordinator
* `drivers/CdpTimeDriver.ts:6` - Virtual time driver
* `strategies/CanvasStrategy.ts` - Canvas-to-video path

### Player (`@helios-project/player`)

Web Component for browser-based preview.

**Responsibilities:**

* Sandboxed iframe rendering
* Transport controls UI
* Timeline scrubbing
* Client-side export (WebCodecs)

### Studio (`@helios-project/studio`)

Visual composition editor (currently in beta).

**Responsibilities:**

* Visual timeline editing
* Asset management
* Real-time preview
* Export workflows

## Framework-agnostic design

The core engine is a vanilla TypeScript class with zero framework dependencies. Framework adapters provide idiomatic APIs:

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useVideoFrame } from '@helios-project/react';

    function MyComponent() {
      const { currentFrame, currentTime } = useVideoFrame();
      return <div>Frame: {currentFrame}</div>;
    }
    ```
  </Tab>

  <Tab title="Vue">
    ```typescript theme={null}
    import { useVideoFrame } from '@helios-project/vue';

    export default {
      setup() {
        const { currentFrame, currentTime } = useVideoFrame();
        return { currentFrame, currentTime };
      }
    };
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    import { Helios } from '@helios-project/core';

    const helios = new Helios({ duration: 10, fps: 30 });

    helios.subscribe(({ currentFrame, currentTime }) => {
      console.log(`Frame ${currentFrame} at ${currentTime}s`);
    });
    ```
  </Tab>
</Tabs>

## Signal-based reactivity

Helios uses a custom signal implementation for fine-grained reactivity:

```typescript theme={null}
// Internal implementation (simplified)
class Helios {
  private _currentFrame: Signal<number>;
  private _currentTime: ReadonlySignal<number>;

  constructor(options) {
    this._currentFrame = signal(0);
    this._currentTime = computed(() => 
      this._currentFrame.value / this._fps.value
    );
  }

  seek(frame: number) {
    this._currentFrame.value = frame; // Triggers subscribers
  }
}
```

This enables:

* **Efficient updates**: Only changed values trigger re-renders
* **Computed values**: Derived state updates automatically
* **Framework adapters**: Easy integration with React, Vue, etc.

See `packages/core/src/signals.ts` for the full implementation.

## Stability and determinism

Deterministic rendering requires waiting for all asynchronous operations to complete before capturing each frame.

### Stability checks

Helios waits for:

1. **Fonts**: `document.fonts.ready`
2. **Images**: `img.decode()` for all images
3. **Media elements**: `seeked` event after seeking video/audio
4. **Custom checks**: User-registered async operations

```typescript theme={null}
await helios.waitUntilStable();
```

This method is called automatically during rendering, but you can also use it for deterministic testing.

### Custom stability checks

Register custom async operations that should block rendering:

```typescript theme={null}
helios.registerStabilityCheck(async () => {
  // Wait for Three.js scene to finish loading
  await scene.loadAssets();
});
```

See `Helios.ts:876` for the stability check API.

## Advantages of this architecture

### Performance

* **Hardware acceleration**: Browser's C++ compositor handles all interpolation
* **Optimized rendering**: Same engine that powers the web
* **Zero JavaScript overhead**: No per-frame calculation loops

### Maintainability

* **Declarative CSS**: Animation logic lives in stylesheets, not code
* **Separation of concerns**: Styling vs. logic
* **Less code**: Browser does the heavy lifting

### Familiarity

* **Standard web APIs**: CSS `@keyframes`, WAAPI, `requestAnimationFrame`
* **Transferable skills**: Existing web development knowledge applies
* **Library compatibility**: Works with GSAP, Framer Motion, Motion One, etc.

<Info>
  This architecture is a bet on native platform capabilities. If you need maximum compatibility or control over every interpolated value, simulation-based approaches like Remotion may be more appropriate.
</Info>

## Trade-offs and constraints

### Browser dependency

Helios requires Chromium for production rendering (CDP access). This is a harder dependency than simulation-based approaches that can run in any JavaScript environment.

### Time control limitations

CDP virtual time is powerful but Chromium-specific. Other browsers don't expose equivalent APIs (yet).

### Learning curve for advanced use cases

While basic CSS animations "just work," advanced scenarios (canvas rendering, complex synchronization) may require understanding Helios's driver system.

## Next steps

* Learn about [compositions](/concepts/compositions) and how to structure your projects
* Explore [timeline control](/concepts/timeline-control) for playback and seeking
* Understand the [animation system](/concepts/animations) in depth
* Dive into [drivers](/concepts/drivers) for custom time control