# @fourier-video/core

`@fourier-video/core` is the shared integration module used by the Fourier SDK and Render Engine. It owns artifact protocol validation, artifact compilation, deterministic DOM timeline sampling, exact rational time, browser runtime control, and standalone artifact MP4 rendering.

Standalone video export also supports the experimental `FAST_RENDER=1` switch and a `FAST_RENDER_SPEED` clock multiplier (default `4`). Pass `fastRender` / `fastRenderSpeed` to `renderVisualArtifactVideo()` to override the environment. A timeline runtime opts in explicitly with `createTimelineRuntime({ fastRender: true, fastRenderSpeed: 8 })`; eligible instances expose `captureFrames()` for continuous alpha PNG capture. Skipped intermediate states repeat the preceding image so output FPS and duration stay fixed. Preview/testing runtimes remain deterministic by default. See the [Render Engine guide](../fourier-render-engine/README.md#experimental-fast_render) for behavior and tradeoffs.

Set `FAST_RENDER-PARA=n` (shell: `env 'FAST_RENDER-PARA=4' …`) or pass `fastRenderParallel: n` to export with multiple DOM frame workers; this also works with deterministic capture. Dynamic standalone exports stream sampled PNGs directly into parallel lossless encoders before final H.264 encoding, avoiding intermediate PNG files. Fast capture uses fixed absolute frame ranges and includes the shard count in its cache profile. `createTimelineRuntime({ fastRender: true, fastRenderParallel: 4 })` opts in explicitly; `captureParallelFrames()` from `@fourier-video/core/timeline` distributes ranges across open instances and reports absolute frame indices (callbacks across pages may arrive out of order). Explicit parallel exports use isolated browser contexts and remove Linux’s single-page/process limit. Default Linux exports retain their container constraints. `runtime.openMany()` atomically leases the available page slots so multiple render nodes can share the runtime without partial-acquisition deadlocks; closing each instance returns its slot. See [parallel rendering](../fourier-render-engine/README.md#parallel-rendering).

The primary seam is `createArtifactHost({ resolveAuthorImport })`. Integrators provide an adapter that resolves author runtime imports from their own installation location:

```ts
import { createArtifactHost } from "@fourier-video/core";

const host = createArtifactHost({
  resolveAuthorImport: (specifier) => Bun.resolveSync(specifier, import.meta.dir),
});
```

Core deliberately has no package or static source dependency on `@fourier-video/sdk`. The SDK and Render Engine each own their adapter. Artifact authors should continue importing author-facing definitions, React, Motion, Three.js, Universe, and project declarations from `@fourier-video/sdk`; Core is a foundation package for SDK/render integration rather than the recommended authoring entry point.

## Public subpaths

- `@fourier-video/core`: host creation, the canonical `CoreError`, ABI constants, and integration types.
- `@fourier-video/core/artifact`: host and artifact compile/render types.
- `@fourier-video/core/timeline`: exact time utilities, `SampleClock`, DOM timeline runtime, and sampling types.
- `@fourier-video/core/protocol`: artifact symbol, ABI/schema constants, compatibility checks, and metadata wire types.

## Execution mode

Project materialization and artifact inspection use the sandboxed Chromium evaluator by default. Set `FOURIER_SECURE_EXECUTION=0` in the host environment to execute trusted local projects in native Node/Bun workers instead. `false` and `off` also disable it (case-insensitive); unset it or use `1` to restore secure execution.

Local workers bypass the secure evaluator's admission queue, wall-clock timeout, CPU/memory monitoring, and blocked host/network APIs. Author code runs with the current user's permissions. Cancellation still terminates workers, and source/import, payload, and protocol validation remain in place. This setting applies to both profiles and does not change the browser used to render DOM/Shader frames. HTTP job workers inherit the host's setting; requests cannot override it.

## Verification

```bash
bun run typecheck
bun test
bun run test:dom
bun run prepack
```