onda-engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+export { DURATION, DurationToken, OVERSHOOT, SPRING_SMOOTH, SPRING_SNAPPY, STAGGER, staggerFrames } from './motion.js';
+export { HOUSE_EASE } from './easing.js';
+export { TIME_DESCRIPTION, TimeInput, framesOf, timeSchema } from './time.js';
+export { COMPONENT_SETTLE, FitToClipOpts, SettleFn, settleTime, staggeredSettle, useTimeScale } from './timing.js';
+export { FontMetrics, GlyphInfo, MeasureOpts, TextMetrics, fontMetrics, glyphLayout, loadFont, measureText, preloadTextMetrics, useFontMetrics, useGlyphLayout, useTextMetrics, useTextMetricsReady } from './text-metrics.js';
+export { Divergence, DivergenceOpts, RenderBackend, divergenceReport, matchesExport } from './divergence.js';
+export { Backend, COMPONENT_FIDELITY, ComponentFidelity, ENGINE_CAPABILITIES, FIDELITY_SUMMARY, Fidelity, RECOMMENDED_PALETTE } from './fidelity.js';
+export { MANIFEST, MANIFEST_NAMES, ManifestEntry, PropMeta, compactCatalog, firstClassEntries, manifestEntry } from './manifest.js';
+export { GlyphCell, GlyphLine, GlyphLineOpts, LINE_RATIO, layoutGlyphLine, lineStartX, lineTopY } from './glyph-line.js';
+export { FitOpts, ResolvedBounds, fitFontSize, fitMaxWidth, useFittedFontSize, useResolvedBounds } from './bounds.js';
+export { ElementSize, FrameSize, PLACEMENT_DESCRIPTION, PLACEMENT_REGIONS, Placed, PlacedProps, Placement, PlacementPoint, PlacementRegion, PlacementShift, PlacementShiftProps, ResolvedPlacement, SAFE_MARGIN, isPlacement, placementSchema, resolvePlacement, usePlacement } from './placement.js';
+export { Theme, ThemeProvider, ThemeProviderProps, defaultTheme, useTheme } from './theme.js';
+export { Motion, PatternInput, entryFade, entryFadeRise, entryScale, entrySlide, exitFade, exitFadeFall, exitScale, exitSlide, heroReveal, stateSwap } from './choreography.js';
+export { EntranceOptions, EntranceType, useEntrance, useSceneProgress, useSpringValue, useStaggeredEntrance, useTextReveal } from './hooks.js';
+export { AudioAnalyzer, Beats, BeatsHandle, beatPulse, framesSinceBeat, isBeat, useAudioBeats, useAudioData } from './audio.js';
+export { AudioClip, AudioClipProps } from './components/AudioClip.js';
+export { AudioVisualizer, AudioVisualizerProps } from './components/AudioVisualizer.js';
+export { BarChart, BarChartDatum, BarChartProps } from './components/BarChart.js';
+export { BentoGrid, BentoGridProps, BentoItem } from './components/BentoGrid.js';
+export { BlurReveal, BlurRevealProps } from './components/BlurReveal.js';
+export { BoundingBox, BoundingBoxProps } from './components/BoundingBox.js';
+export { BrowserFrame, BrowserFrameProps } from './components/BrowserFrame.js';
+export { Button, ButtonProps } from './components/Button.js';
+export { Callout, CalloutDirection, CalloutProps } from './components/Callout.js';
+export { CameraShake, CameraShakeProps } from './components/CameraShake.js';
+export { CardShowcase, CardShowcaseProps } from './components/CardShowcase.js';
+export { CaptionEntry, Captions, CaptionsProps } from './components/Captions.js';
+export { ChapterCard, ChapterCardProps } from './components/ChapterCard.js';
+export { CodeBlock, CodeBlockProps } from './components/CodeBlock.js';
+export { CodeDiff, CodeDiffProps, DiffLine, DiffLineType } from './components/CodeDiff.js';
+export { Confetti, ConfettiProps } from './components/Confetti.js';
+export { CountUp, CountUpProps } from './components/CountUp.js';
+export { Cursor, CursorProps } from './components/Cursor.js';
+export { DeviceFrame, DeviceFrameProps } from './components/DeviceFrame.js';
+export { DrawOn, DrawOnProps } from './components/DrawOn.js';
+export { DynamicGrid, DynamicGridProps } from './components/DynamicGrid.js';
+export { EndCard, EndCardProps } from './components/EndCard.js';
+export { FadeIn, FadeInProps } from './components/FadeIn.js';
+export { FadeOut, FadeOutProps } from './components/FadeOut.js';
+export { FilmGrade, FilmGradeProps, FilmLook } from './components/FilmGrade.js';
+export { GradientShift, GradientShiftProps } from './components/GradientShift.js';
+export { GrainOverlay, GrainOverlayProps } from './components/GrainOverlay.js';
+export { Highlight, HighlightProps } from './components/Highlight.js';
+export { IconPop, IconPopProps, IconShape } from './components/IconPop.js';
+export { ImageReveal, ImageRevealFit, ImageRevealMotion, ImageRevealProps } from './components/ImageReveal.js';
+export { InputField, InputFieldProps } from './components/InputField.js';
+export { KanbanBoard, KanbanBoardProps, KanbanColumn } from './components/KanbanBoard.js';
+export { KenBurns, KenBurnsProps } from './components/KenBurns.js';
+export { Ease, Keyframes, KeyframesImageContent, KeyframesProps, KeyframesTextContent, PosKey, ValKey } from './components/Keyframes.js';
+export { KeyframeTracks, SampledKeyframes, hasKeyframeTracks, sampleKeyframes, sampleTrack } from './keyframes-sampler.js';
+export { Box, ResponsiveTransform, entryDesignAnchor, responsiveEntryTransform } from './responsive.js';
+export { KineticText, KineticTextPreset, KineticTextProps } from './components/KineticText.js';
+export { LineChart, LineChartProps } from './components/LineChart.js';
+export { LogoReveal, LogoRevealPreset, LogoRevealProps } from './components/LogoReveal.js';
+export { LogoSting, LogoStingProps } from './components/LogoSting.js';
+export { LookbookLayout, LookbookShot, LookbookShotProps } from './components/LookbookShot.js';
+export { LowerThird, LowerThirdProps } from './components/LowerThird.js';
+export { Marquee, MarqueeProps } from './components/Marquee.js';
+export { MaskReveal, MaskRevealProps } from './components/MaskReveal.js';
+export { MatrixDecode, MatrixDecodeProps } from './components/MatrixDecode.js';
+export { MeshGradient, MeshGradientProps } from './components/MeshGradient.js';
+export { Moodboard, MoodboardProps } from './components/Moodboard.js';
+export { NodeGraph, NodeGraphProps, Satellite } from './components/NodeGraph.js';
+export { Parallax, ParallaxLayer, ParallaxProps } from './components/Parallax.js';
+export { PathMorph, PathMorphProps } from './components/PathMorph.js';
+export { PieReveal, PieRevealProps, PieRevealSlice } from './components/PieReveal.js';
+export { PriceTag, PriceTagProps } from './components/PriceTag.js';
+export { PricingCard, PricingCardProps } from './components/PricingCard.js';
+export { ProductWall, ProductWallProps } from './components/ProductWall.js';
+export { ProgressBar, ProgressBarProps } from './components/ProgressBar.js';
+export { ProgressSteps, ProgressStepsProps } from './components/ProgressSteps.js';
+export { PulsingIndicator, PulsingIndicatorProps } from './components/PulsingIndicator.js';
+export { QuoteCard, QuoteCardProps } from './components/QuoteCard.js';
+export { RgbGlitch, RgbGlitchProps } from './components/RgbGlitch.js';
+export { RotateIn, RotateInProps } from './components/RotateIn.js';
+export { ScaleIn, ScaleInProps } from './components/ScaleIn.js';
+export { Scrim, ScrimProps } from './components/Scrim.js';
+export { SiteReveal, SiteRevealProps } from './components/SiteReveal.js';
+export { ShimmerSweep, ShimmerSweepProps } from './components/ShimmerSweep.js';
+export { SkeletonCard, SkeletonCardProps } from './components/SkeletonCard.js';
+export { SlideIn, SlideInProps } from './components/SlideIn.js';
+export { SlideOut, SlideOutProps } from './components/SlideOut.js';
+export { SlotMachineRoll, SlotMachineRollProps } from './components/SlotMachineRoll.js';
+export { SplitScreen, SplitScreenProps } from './components/SplitScreen.js';
+export { Spotlight, SpotlightProps } from './components/Spotlight.js';
+export { SpotlightCard, SpotlightCardProps } from './components/SpotlightCard.js';
+export { StaggerGroup, StaggerGroupProps } from './components/StaggerGroup.js';
+export { SplitLockup, SplitLockupProps } from './components/SplitLockup.js';
+export { StatCard, StatCardProps } from './components/StatCard.js';
+export { Terminal, TerminalProps } from './components/Terminal.js';
+export { TextAnimate, TextAnimator, TextAnimatorDirection, TextAnimatorProps, TextAnimatorUnit } from './components/TextAnimator.js';
+export { TextFadeReplace, TextFadeReplaceProps } from './components/TextFadeReplace.js';
+export { Timeline, TimelineEvent, TimelineProps } from './components/Timeline.js';
+export { TitleCard, TitleCardProps } from './components/TitleCard.js';
+export { TrackingIn, TrackingInProps } from './components/TrackingIn.js';
+export { Typewriter, TypewriterProps } from './components/Typewriter.js';
+export { Underline, UnderlineProps } from './components/Underline.js';
+export { VideoClip, VideoClipProps } from './components/VideoClip.js';
+export { Vignette, VignetteProps } from './components/Vignette.js';
+export { WordRotate, WordRotateProps } from './components/WordRotate.js';
+export { WordStagger, WordStaggerProps } from './components/WordStagger.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from 'onda-engine/components';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js","sourcesContent":[]}

package/dist/manifest-7N3yu9tB.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+
+type Fidelity = 'first_class' | 'degraded' | 'apes_remotion';
+type Backend = 'both' | 'gpu_only';
+interface ComponentFidelity {
+    fidelity: Fidelity;
+    engineNative: boolean;
+    needsFeature: string | null;
+    backend: Backend;
+}
+declare const COMPONENT_FIDELITY: Record<string, ComponentFidelity>;
+declare const FIDELITY_SUMMARY: {
+    readonly firstClass: 72;
+    readonly degraded: 0;
+    readonly apesRemotion: 0;
+};
+/** The safe, recommended palette: every first-class component. An agent can
+ *  default to these in one read and only escalate to degraded ones on demand. */
+declare const RECOMMENDED_PALETTE: readonly string[];
+/** Engine capability statement — what the agent should lean on, and what it must
+ *  NOT author for. The "don't chase" features want a filter/blend/3D pipeline the
+ *  vector engine deliberately omits; the engine's job is the best deterministic
+ *  GPU vector renderer, not a headless browser. */
+declare const ENGINE_CAPABILITIES: {
+    readonly supported: readonly ["vector fills / strokes (cap/join/dash) / rounded-rect / arbitrary Bézier paths", "linear + radial gradients with stops (CPU + GPU)", "per-glyph vector text (resolution-independent) with letter-spacing / tracking", "author-time text metrics (measureText width; fontMetrics capHeight/xHeight/capTop; glyphLayout kerning-accurate per-char positions)", "taffy flexbox layout (direction/justify/align/gap/padding/wrap)", "2D affine transforms (translate / scale / rotate) with transform-origin pivot", "clipping (rect / ellipse / path) in local space", "images + video frames with cover/contain/fill fit", "audio decode + FFT spectrum (symphonia + rustfft) + multi-track mix + mux into export", "AUDIO-DRIVEN MOTION (sync to music) — `useAudioBeats(src)` analyzes a clip into `{ tempo, beats, onsets, onsetEnv }` in FRAME units (deterministic, preview == export). Drive motion with the pure helper `beatPulse(frame, beats, decay)` (a 1→0 punch on each beat): `scaleX={1 + 0.3 * beatPulse(frame, b.beats)}` HITS an element on the beat; `isBeat(frame, beats)` for hard cuts; `onsetEnv[frame]` (0..1) for transient-driven glows. The \"edited TO the music\" layer — cut on the beat, punch on the kick, drop text on a transient. Both backends + live preview", "deterministic CPU==GPU verification; parallel frame export", "blend modes (multiply / screen / overlay / soft-light / …, GPU)", "procedural film grain (onda-noise source + overlay blend, GPU)", "drop-shadow / glow (analytic blurred rounded-rect)", "animated image blur — gaussian focus-pull in the image pass (CPU+GPU+native byte-identical)", "content/text blur — screen-space gaussian over an arbitrary subtree (Group/Text/…) via the render-to-texture pass; the `blur` sugar prop, ramps for soft→sharp reveals (CPU+GPU)", "backdrop blur — frosted-glass blur of what is BEHIND a node (CSS `backdrop-filter`); the `backdropBlur` node prop samples the already-composited backdrop, blurs + tints + brightens it, and draws it as the node’s backing (Vello samples the rendered backdrop, the CPU reference its live framebuffer)", "mattes / masks — reveal one subtree THROUGH another's shape (CSS mask-image / SVG mask): the `matte` node prop (+ matteMode 'alpha'|'luminance') renders content + matte to textures and multiplies alpha — media-through-type, shape wipes, gradient reveals (render-to-texture)", "precomp / adjustment layers — `<Precomp>` flattens a subtree to ONE layer (render-to-texture) so its opacity/blend apply to the COMPOSITED result, not per-child (fixes fading-a-group double-darkening overlaps; AE precomp / collapse-transformations); an adjustment layer = a `<Group>` with an effect wrapping the layers below it. Both backends", "bloom / glow — bright-pass → large-σ blur → additive composite, the single biggest premium tell; the `bloom` node prop (CPU+GPU)", "cinematic color grade — per-pixel exposure / contrast / saturation / temperature / tint; the `grade` node prop, the \"land mixed/AI media into one look\" wedge (CPU+GPU)", "goo / metaball morph — blur → alpha-threshold so overlapping shapes fuse into liquid forms with smooth necks; the `goo` node prop (GPU)", "light-wrap — the blurred backdrop's light bleeds onto a cut-out node's feathered EDGES (the #1 'shot in, not pasted on' tell for landing a plate); the `lightWrap` node prop (GPU/export)", "directional / motion blur — a 1D gaussian smear of std-dev σ along an angle (the in-motion streak); the `directionalBlur` node prop (CPU+GPU)", "per-pixel stylize, one shared compute pipeline: `chromaticAberration` (lens RGB split), `vignette` (radial edge darkening), `posterize` (quantize to N levels), `duotone` (luminance → two colors), `chromaKey` (green-screen knock-out with despill) — all CPU+GPU node props", "fBm fractal-noise ANIMATED gradients (GPU compute over 2D simplex + domain-warp); CPU reference + WebGPU preview degrade to a smooth gradient, so judge on the native render", "composition-level cinematic FINISH — a scene-linear HDR chain (bloom + warm halation + grade + vignette + grain) ending in ONE ACES film tone-map; the \"looks shot\" output transform via `<Composition finish={…}>` (GPU/export-only — preview/CPU render un-finished)", "per-object MOTION BLUR — shutter-angle temporal supersampling via `<Composition motionBlur={…}>`: every moving element smears by its OWN motion (translation/rotation/scale), static stays sharp (export-only, N× render cost)", "trim paths — `trimStart`/`trimEnd`/`trimOffset` (0..1) on any stroked shape draw only that arc-length slice of the outline; the mograph line-draw, animate `trimEnd` 0→1 (CPU+GPU)", "repeater — `<Repeater count offsetX offsetY rotation scale startOpacity endOpacity>` stamps a subtree with COMPOUNDING transforms: grids (nest two), radial arrays, spirals, motion trails (all backends)", "boolean ops (merge paths) — `<Merge op=\"union|difference|intersect|xor\">` combines shape children into ONE outline (ring = circle−circle, lens = circle∩circle, speech bubble = rect∪triangle); curves flattened, resolved on both backends (i_overlay)", "particles — `<Particles count seed x y speed angle spread gravity lifetime emitOver loop size opacity colors spin>` is a DETERMINISTIC emitter (bursts / fountains / confetti / sparks / dust / snow): every particle is a pure function of frame+seed+index, frame-based, rendered as plain shapes (position/size/opacity/colour are CPU==GPU; `spin` is rotation → GPU-only)", "Camera — pan / zoom viewport primitive for 2.5D camera moves", "depth of field — 2.5D rack focus: layers carry a `depth`, the comp sets `dof={{ focus, aperture }}`, and each layer defocuses by its distance from the focus plane (animate `focus` for a focus pull); resolves to a per-layer blur, so both backends + live preview", "3D SCENE (3D layers + perspective camera) — `<Scene3D camera={{ position, target, fov }}>` places its children in ONE shared 3D world: each is a flat plane positioned by `position3d={[x,y,z]}` (z INTO the screen, AE convention) and tilted by `rotation3d={[x,y,z]}` degrees, viewed through a perspective camera with a real depth buffer (occlude + intersect by true depth). Camera fly-throughs, card walls / cover-flow, parallax, exploded UI. z=0 + no rotation == the 2D placement. GPU = true perspective + out-of-plane rotation; CPU/web preview degrade to a 2.5D depth-sorted projection (scale + position, no tilt) → judge 3D on a NATIVE/export render", "EXTRUDED 3D solids (3D logos & titles) — inside a `<Scene3D>`, a shape or text layer becomes a LIT 3D SOLID via `extrude={depth}`: `<Text extrude={80}>ONDA</Text>` / `<Rect extrude={80}>` / `<Path extrude={80}>` grows front + back faces (lyon-tessellated, holes handled) + side walls, shaded by a directional light so it catches the light as it rotates — the spinning solid logo / kinetic 3D title. GPU only; the CPU reference + live preview draw the flat outline → judge on a NATIVE/export render", "no-Chromium export (ffmpeg / GIF / PNG)"];
+    readonly unsupported: readonly [{
+        readonly feature: "imported 3D MODELS / glTF meshes (3D *layers* AND extruded shapes/text ARE supported via <Scene3D> + extrude)";
+        readonly status: "no-model-import";
+    }, {
+        readonly feature: "SVG filters / embedded text+image / gradient paint";
+        readonly status: "flattened-to-solid";
+    }, {
+        readonly feature: "color / emoji glyphs / variable fonts";
+        readonly status: "outline-only";
+    }];
+    readonly backendNotes: "CPU reference (tiny-skia) renders fills, strokes (cap/join/dash), linear+radial gradients, and Bézier paths — byte-identical to Vello for those. It does NOT apply rotation or clipping (Vello-only) or decode video. A 'gpu_only' component needs one of those three; prefer 'both' components for a CPU-verified render.";
+};
+
+/** Per-prop semantic metadata layered on top of the Zod schema. */
+interface PropMeta {
+    /** Prop name. */
+    name: string;
+    /** Underlying value kind — string | number | int | boolean | enum | stringArray … */
+    type: string;
+    /** Semantic role — text | color | fontSize | durationFrames | fraction | url … */
+    role: string;
+    /** Allowed values, when the prop is an enum. */
+    enumValues?: string[];
+    /** The default value (schema-derived, JSON-encoded), when the prop has one.
+     *  Always sourced from the Zod schema so it can't drift from what renders. */
+    default?: string;
+    /** Minimum (inclusive) for a number prop, from the Zod schema. */
+    min?: number;
+    /** Maximum (inclusive) for a number prop, from the Zod schema. */
+    max?: number;
+    /** Display-unit hint for a number prop — 'px' | 'frames' | 'deg'. */
+    unit?: string;
+    /** Defaults to a theme color/font token; the agent should usually OMIT it. */
+    themeable: boolean;
+    /** Must be provided (no default, not optional). */
+    required: boolean;
+    /** One-line description. */
+    description: string;
+}
+/** One catalog entry: identity + curation + capability + the @onda prop schema. */
+interface ManifestEntry {
+    /** kebab-case slug — the scene-graph `component` value. */
+    slug: string;
+    /** PascalCase component name — the `@onda-engine/components` export. */
+    name: string;
+    /** Grouping for the catalog/agent (Text, Data, Media, …). */
+    category: string;
+    /** Short human title. */
+    title: string;
+    /** One-line description for the agent catalog. */
+    description: string;
+    /** When the agent should reach for this. */
+    pickWhen: string;
+    /** Components it commonly composes/pairs with. */
+    composes: string[];
+    /** How it sits in a scene (background | block | overlay | annotation | …). */
+    sceneRole: string;
+    /** full_frame (fills the canvas) | non_occluding (decorates) | centered. */
+    occlusion: string;
+    /** Render fidelity — the agent prefers `first_class`. From `fidelity.ts`. */
+    fidelity: Fidelity;
+    /** `both` (CPU==GPU) | `gpu_only`. From `fidelity.ts`. */
+    backend: Backend;
+    /** True when the look is engine-native (not a CSS-effect approximation). */
+    engineNative: boolean;
+    /** A good example prop set (few-shot for the agent). */
+    example: Record<string, unknown>;
+    /** Per-prop semantic metadata (alongside the Zod schema). */
+    props: PropMeta[];
+    /** The @onda-native Zod schema for this component's props. */
+    schema: z.ZodTypeAny;
+}
+/** The catalog — RAW entries enriched with the live fidelity rating + the
+ *  schema-reconciled prop list (so curated `props` can never drift from `schema`). */
+declare const MANIFEST: ManifestEntry[];
+/** The PascalCase names of every catalogued component. */
+declare const MANIFEST_NAMES: readonly string[];
+/** A capability the director APPLIES (a verb), vs. a `MANIFEST` component (a noun). */
+interface Capability {
+    /** Stable id. */
+    id: string;
+    /** composition (whole-comp) | effect (per-node) | 3d | audio. */
+    category: 'composition' | 'effect' | '3d' | 'audio';
+    /** Short title. */
+    title: string;
+    /** What it does + when to reach for it. */
+    description: string;
+    /** HOW to apply it — the prop/option/API, with a concrete example. */
+    apply: string;
+    /** `both` = CPU==GPU + live preview | `gpu` = needs Vello | `export` = N×-cost, export-only. */
+    backend: 'both' | 'gpu' | 'export';
+    /** A caveat the agent MUST respect (e.g. judge the look on a native render). */
+    note?: string;
+}
+declare const CAPABILITIES: Capability[];
+/** Look up a manifest entry by slug or PascalCase name. */
+declare function manifestEntry(key: string): ManifestEntry | undefined;
+/** Only the first-class components — the agent's safe default palette. */
+declare function firstClassEntries(): ManifestEntry[];
+/** A compact, grouped text catalog for the agent prompt: one bullet per
+ *  component with its fidelity, when-to-use, and its prop roles. */
+declare function compactCatalog(opts?: {
+    firstClassOnly?: boolean;
+}): string;
+
+export { type Backend as B, COMPONENT_FIDELITY as C, ENGINE_CAPABILITIES as E, FIDELITY_SUMMARY as F, MANIFEST as M, type PropMeta as P, RECOMMENDED_PALETTE as R, type ComponentFidelity as a, type Fidelity as b, MANIFEST_NAMES as c, type ManifestEntry as d, compactCatalog as e, firstClassEntries as f, CAPABILITIES as g, type Capability as h, manifestEntry as m };

package/dist/player.d.ts

@@ -0,0 +1,177 @@
+import { Scene, Color } from './scene.js';
+import * as react from 'react';
+import { ReactElement } from 'react';
+
+/** Paints a scene onto a 2D context. The default is {@link drawScene}; the
+ *  playground and `<Player>` swap in a WASM-engine drawer (real renderer →
+ *  `putImageData`) when `@onda-engine/wasm` is present. */
+type FrameDrawer = (ctx: CanvasRenderingContext2D, scene: Scene) => void;
+/** Draw `scene` onto `ctx`, clearing first. The context should be sized to the
+ *  composition's resolution. */
+declare function drawScene(ctx: CanvasRenderingContext2D, scene: Scene): void;
+/** Convert the engine's 0..1 straight-alpha sRGB color to a CSS `rgba()`. */
+declare function cssColor(color: Color): string;
+
+/** A rendered frame as returned by `@onda-engine/wasm`'s `OndaEngine.render`: a flat
+ *  straight-alpha RGBA8 buffer plus dimensions. */
+interface RenderedFrame {
+    readonly width: number;
+    readonly height: number;
+    readonly pixels: Uint8Array | Uint8ClampedArray;
+}
+/** The minimal shape of `@onda-engine/wasm`'s `OndaEngine` the player needs. Structural
+ *  typing avoids a build/runtime dependency on the wasm package. */
+interface RenderEngine {
+    /** Rasterize a scene-graph JSON document to RGBA8 pixels. */
+    render(sceneJson: string): RenderedFrame;
+}
+/**
+ * Build a {@link FrameDrawer} that paints each frame with the real ONDA engine
+ * (`@onda-engine/wasm`). Construct the engine once and memoize the returned drawer:
+ *
+ * ```tsx
+ * import { OndaEngine, default as initWasm } from '@onda-engine/wasm'
+ * import wasmUrl from '@onda-engine/wasm/pkg/onda_wasm_bg.wasm?url'
+ * import { Player, engineDrawer } from '@onda-engine/player'
+ *
+ * await initWasm(wasmUrl)
+ * const engine = new OndaEngine()
+ * const draw = engineDrawer(engine) // memoize with useMemo in components
+ *
+ * <Player composition={hello} draw={draw} />
+ * ```
+ *
+ * The engine renders the scene to RGBA8 and the drawer blits it with
+ * `putImageData` — pixel-exact, the real renderer.
+ */
+declare function engineDrawer(engine: RenderEngine): FrameDrawer;
+
+/** An async, GPU renderer — structurally `@onda-engine/wasm-vello`'s `VelloEngine`.
+ *  This is the pixel-exact, full-feature path (paths/gradients/clips/AA), so the
+ *  Player prefers it. Accepted structurally so `@onda-engine/player` needn't depend on
+ *  `@onda-engine/wasm-vello`. */
+interface GpuEngine {
+    render(sceneJson: string): Promise<{
+        width: number;
+        height: number;
+        pixels: Uint8Array;
+    }>;
+    /** Optional: load a custom font (`.ttf`/`.otf` bytes) so the live preview draws
+     *  with the same fonts the export will. `@onda-engine/wasm-vello`'s `VelloEngine` exposes
+     *  `load_font`; `@onda-engine/wasm`'s `OndaEngine` exposes `loadFont` — the Player drains
+     *  the `@onda-engine/react` font registry into whichever exists. */
+    loadFont?(data: Uint8Array): unknown;
+    load_font?(data: Uint8Array): unknown;
+}
+interface PlayerProps {
+    /** A `<Composition>` element (from `@onda-engine/react`). */
+    composition: ReactElement;
+    /** Start playing on mount. Default `true`. */
+    autoPlay?: boolean;
+    /** Loop back to frame 0 at the end. Default `true`. Also toggleable in the UI. */
+    loop?: boolean;
+    /**
+     * The renderer. The Player auto-selects the best available, in order:
+     *   1. an explicit {@link PlayerProps.draw},
+     *   2. the GPU engine ({@link PlayerProps.gpuEngine}) — Vello/WebGPU,
+     *      pixel-identical to `onda export`,
+     *   3. the CPU engine ({@link PlayerProps.engine}),
+     *   4. the Canvas2D {@link drawScene} fallback.
+     * It also falls back automatically if a renderer errors at runtime.
+     */
+    draw?: FrameDrawer;
+    /** The GPU (Vello/WebGPU) renderer — preferred when present (see {@link GpuEngine}). */
+    gpuEngine?: GpuEngine;
+    /** The CPU renderer (`@onda-engine/wasm`'s `OndaEngine`) — fallback when there's no GPU. */
+    engine?: RenderEngine;
+    /** Show a small backend indicator (WebGPU/CPU/Canvas2D). Default `true`. */
+    showStatus?: boolean;
+    /** Control visibility. `'auto'` (default) reveals the controls on hover / focus
+     *  / when paused; `'always'` keeps them visible; `'none'` hides them entirely
+     *  (no overlay, no fullscreen button, no click-to-toggle) — a chrome-free
+     *  thumbnail (e.g. a gallery tile that plays on hover + clicks through to a link). */
+    controls?: 'auto' | 'always' | 'none';
+    /** Accessible label for the player region. Default `"ONDA composition player"`. */
+    label?: string;
+    /** Optional className on the root for app-level layout/overrides. */
+    className?: string;
+    /** Frame to start on. Default `0`. Clamped to the composition length. */
+    initialFrame?: number;
+    /** Initial playback speed (preview only — does NOT change the exported video,
+     *  which always renders 1× at the composition fps). `1` = real-time. Forward
+     *  presets in the UI are 0.25×–2×; programmatic values clamp to 0.1×–4×.
+     *  Default `1`. */
+    playbackRate?: number;
+    /** Called whenever the current frame changes (scrub or playback). */
+    onFrameUpdate?: (frame: number) => void;
+    /** Called when playback starts. */
+    onPlay?: () => void;
+    /** Called when playback pauses (or stops at the end of a non-looping clip). */
+    onPause?: () => void;
+}
+/**
+ * Imperative handle for `<Player>` (via `ref`) — drive playback from a host app
+ * such as an editor timeline.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<PlayerHandle>(null)
+ * <Player ref={ref} composition={…} />
+ * ref.current?.seekTo(48)
+ * ```
+ */
+/** Player events (Remotion-`@remotion/player`-compatible) for a host editor to
+ *  sync against — e.g. a canvas overlay tracking the current frame. */
+type PlayerEventType = 'frameupdate' | 'play' | 'pause' | 'seeked' | 'ended' | 'ratechange';
+/** Event passed to a {@link PlayerEventListener}: `detail.frame` is the current
+ *  frame (mirrors Remotion's `CallbackListener` event shape). For `ratechange`,
+ *  `detail.playbackRate` carries the new preview speed. */
+interface PlayerEvent {
+    type: PlayerEventType;
+    detail: {
+        frame: number;
+        playbackRate?: number;
+    };
+}
+type PlayerEventListener = (event: PlayerEvent) => void;
+interface PlayerHandle {
+    /** Seek to a frame (clamped). Does not change the play/pause state. */
+    seekTo(frame: number): void;
+    /** Start playing (restarts from 0 if at the end of a non-looping clip). */
+    play(): void;
+    /** Pause playback. */
+    pause(): void;
+    /** Toggle play/pause. */
+    toggle(): void;
+    /** The current frame. */
+    getCurrentFrame(): number;
+    /** Total frames in the composition. */
+    getTotalFrames(): number;
+    /** Whether playback is currently running. */
+    isPlaying(): boolean;
+    /** The current preview playback speed (1 = real-time). */
+    getPlaybackRate(): number;
+    /** Set the preview playback speed (clamped to 0.1×–4×). Preview only — does
+     *  not affect export. Emits a `ratechange` event. */
+    setPlaybackRate(rate: number): void;
+    /** Subscribe to a player event
+     *  (`frameupdate`/`play`/`pause`/`seeked`/`ended`/`ratechange`).
+     *  Mirrors `@remotion/player`'s `addEventListener` so an editor built against
+     *  Remotion's Player ports without rewiring its frame-sync/overlay. */
+    addEventListener(type: PlayerEventType, listener: PlayerEventListener): void;
+    /** Unsubscribe a listener previously passed to {@link addEventListener}. */
+    removeEventListener(type: PlayerEventType, listener: PlayerEventListener): void;
+}
+/**
+ * Render an ONDA composition to a canvas with play/pause, a frame scrubber, a
+ * loop toggle, and a frame/time readout.
+ *
+ * @example
+ * ```tsx
+ * import { Player } from '@onda-engine/player'
+ * <Player composition={<Composition …>…</Composition>} engine={ondaEngine} />
+ * ```
+ */
+declare const Player: react.ForwardRefExoticComponent<PlayerProps & react.RefAttributes<PlayerHandle>>;
+
+export { type FrameDrawer, Player, type PlayerEvent, type PlayerEventListener, type PlayerEventType, type PlayerHandle, type PlayerProps, type RenderEngine, type RenderedFrame, cssColor, drawScene, engineDrawer };