@miraiclip/react

npm install @miraiclip/react

FunctionsCopy Anchor Link

isEditableTargetCopy Anchor Link

True for inputs, text areas, selects and contenteditable: keys there belong to the field.

function isEditableTarget(target: EventTarget | null): boolean

PlaybackProviderCopy Anchor Link

Playback and preview for the project above it: a preview controller (renderer, player, fallback clock, monitoring volume) exposed as React state. Transport state comes from player events, so it never drifts from what the player is doing.

function PlaybackProvider({ options, volumeStorageKey, children }: PlaybackProviderProps): react.JSX.Element

Guides: Preview & playback, Overview, Preview, Timeline

ProjectProviderCopy Anchor Link

Provides one Miraiclip project to everything below it. Pass init (and optionally seed) to have the provider create the project once for its lifetime, or project to share one you created.

function ProjectProvider(props: ProjectProviderProps): react.JSX.Element

Guides: Overview, Timeline, Installation, React

ProjectSessionProviderCopy Anchor Link

A <ProjectProvider> whose project can be swapped at runtime (Open / New). Loading remounts everything below it, so engine, renderer and UI all re-initialize cleanly from the loaded state.

function ProjectSessionProvider({ initial, children }: {
    initial: SessionInit;
    children: ReactNode;
}): react.JSX.Element

Guides: React

rulerStepUsCopy Anchor Link

Smallest "nice" tick step that keeps ticks at least minGapPx apart.

function rulerStepUs(pxPerSecond: number, minGapPx?: number): Us

Guides: Timeline, React

shallowEqualCopy Anchor Link

Shallow equality for arrays and objects of primitives — for list selectors.

function shallowEqual<T>(a: T, b: T): boolean

Guides: React

useClipCopy Anchor Link

function useClip(clipId: string | null | undefined): Clip | undefined

Guides: React

useClipCountCopy Anchor Link

How many clips a track has.

function useClipCount(trackId: string): number

Guides: React

useClipsCopy Anchor Link

A track's clips, sorted by start time.

function useClips(trackId: string): Clip[]

Guides: Reading state, Installation, React

useCommandsCopy Anchor Link

Typed command builders bound to the current project. Stable across renders.

function useCommands(): Commands

Guides: Blocks, React

useCompositorPlayheadCopy Anchor Link

Moves a playhead-driven element without per-frame style recalcs.

While playing, the element runs a linear Web Animations transform from the playhead to the end, so the browser's compositor moves it with no main- thread work. The store's playhead only re-syncs it: the animation restarts when the real playhead drifts more than toleranceUs from its prediction (seek, loop, buffering stall). Paused, it gets a static transform.

toTransform maps a time to a CSS transform; list what it depends on in deps.

function useCompositorPlayhead(ref: RefObject<HTMLElement | null>, toTransform: (us: Us, durationUs: Us) => string, deps: readonly unknown[], toleranceUs?: number): void

Guides: Timeline, React

useDurationUsCopy Anchor Link

Composition length: the end of the last clip. Recomputed only on edits.

function useDurationUs(): Us

Guides: React

useEditorShortcutsCopy Anchor Link

Binds the default editor keys (see matchEditorShortcut) on window, limited to actions. Keys typed into text fields are left alone.

function useEditorShortcuts(actions?: readonly EditorAction[]): void

Guides: Selection & canvas editing, Blocks, Timeline, React

useGestureCopy Anchor Link

Start a live edit that lands in history as one entry (see beginGesture).

function useGesture(): (label: string) => Gesture

Guides: Blocks, React

useHistoryStateCopy Anchor Link

function useHistoryState(): {
    canUndo: boolean;
    canRedo: boolean;
}

usePlaybackCopy Anchor Link

Transport, preview and volume from the nearest <PlaybackProvider>.

function usePlayback(): PlaybackValue

Guides: Preview, Installation, React

usePlayheadFollowCopy Anchor Link

Keeps the playhead findable: while playing, pages the timeline so the playhead stays in view (pausing for 1.5 s after the user scrolls by hand), and reports when it is off screen, for an edge indicator.

function usePlayheadFollow(scrollRef: RefObject<HTMLElement | null>, pxPerSecond: number, headerWidthPx?: number): PlayheadFollow

Guides: React

usePlayheadRefCopy Anchor Link

The playhead in a ref that updates without re-rendering. Pass onChange to write to the DOM directly on each change (e.g. a time label's textContent).

function usePlayheadRef(onChange?: (us: Us) => void): MutableRefObject<Us>

Guides: React

usePlayheadUsCopy Anchor Link

Playhead position in µs. Re-renders on every played frame (60×/s), so use it only in small components; usePlayheadRef reads it without re-rendering.

function usePlayheadUs(): Us

Guides: Reading state, Scrubber, React

usePreviewCopy Anchor Link

Size and status of the enclosing <Preview>, for overlays.

function usePreview(): PreviewState

Guides: Overview, Preview, React

useProjectCopy Anchor Link

The project from the nearest <ProjectProvider>.

function useProject(): Project

Guides: React

useProjectSessionCopy Anchor Link

Open / New for the nearest <ProjectSessionProvider>.

function useProjectSession(): ProjectSession

Guides: React

useProjectStateCopy Anchor Link

Subscribe to a slice of project state. Re-renders only when the selected value changes (per isEqual, default Object.is). Every other state hook builds on this one; narrow selectors keep a busy timeline cheap.

function useProjectState<T>(selector: (state: ProjectState) => T, isEqual?: (a: T, b: T) => boolean): T

Guides: Reading state, Scrubber, React

useSelectedClipCopy Anchor Link

The selected clip when exactly one is selected.

function useSelectedClip(): Clip | undefined

Guides: Blocks, React

useSelectionCopy Anchor Link

Selected clip ids.

function useSelection(): string[]

Guides: Reading state, Preview, React

useSettingsCopy Anchor Link

Project settings (size, frame rate, name).

function useSettings(): ProjectSettings

Guides: React

useTimelineCopy Anchor Link

The timeline's scale, layout and drag entry point. Use inside <Timeline.Root>.

function useTimeline(): TimelineContextValue

Guides: Timeline, React

useTimelineClipCopy Anchor Link

State of the enclosing <Timeline.Clip>, live while it is dragged.

function useTimelineClip(): TimelineClipState

Guides: Overview, Timeline, Waveform, React

useTimelineDragCopy Anchor Link

The clip being dragged, as it would land now; null when no drag is in progress.

function useTimelineDrag(): ClipDragPreview | null

Guides: Timeline, React

useTimelineRangeCopy Anchor Link

The time range the viewport shows (plus a margin), for virtualising custom rows.

function useTimelineRange(): {
    fromUs: Us;
    toUs: Us;
}

Guides: Timeline, React

useTimelineTrackCopy Anchor Link

The track of the enclosing <Timeline.Track>.

function useTimelineTrack(): Track

Guides: Timeline, React

useTimelineZoomCopy Anchor Link

Ctrl/⌘ + wheel zooms the timeline around the pointer; plain wheel keeps scrolling.

function useTimelineZoom(scrollRef: RefObject<HTMLElement | null>, options: TimelineZoomOptions): void

Guides: Timeline, React

useTrackCopy Anchor Link

function useTrack(trackId: string): Track | undefined

Guides: React

useTrackOrderCopy Anchor Link

Track ids in render order (index 0 = bottom layer).

function useTrackOrder(): string[]

Guides: React

useTracksCopy Anchor Link

All tracks, in render order.

function useTracks(): Track[]

Guides: React

useTransformBoxCopy Anchor Link

State of the enclosing <TransformBox.Root>, for custom handles and drawing.

function useTransformBox(): TransformBoxState

Guides: Overview, Transform box, React

useTransitionsCopy Anchor Link

A track's transitions.

function useTransitions(trackId: string): Transition[]

Guides: React

useUndoRedoCopy Anchor Link

Undo and redo, with live availability for the buttons.

function useUndoRedo(): UndoRedo

Guides: React

useVisibleRangeCopy Anchor Link

The time range a scrolling timeline should render (see visibleRange in

function useVisibleRange(scrollRef: RefObject<HTMLElement | null>, pxPerSecond: number, headerWidthPx?: number): {
    fromUs: Us;
    toUs: Us;
}

Guides: Timeline, React

useWaveformPeaksCopy Anchor Link

Waveform peaks for an audio or video asset, or null while computing (and when it has no audio). Computed once per asset src with a streamed decode, shared by every component that asks, one asset at a time.

function useWaveformPeaks(asset: Asset | undefined): WaveformPeaks | null

Guides: Timeline, Overview, Waveform, React

ConstantsCopy Anchor Link

PreviewCopy Anchor Link

The preview canvas, wired to <PlaybackProvider>: hands its <canvas> to the renderer on mount, keeps the render target matched to its size, and releases it on unmount. The element is position: relative and exactly the canvas's size, so overlays can use position: absolute; inset: 0. data-mode carries the playback mode; data-error is set after a render error.

const Preview: react.ForwardRefExoticComponent<PreviewProps & react.RefAttributes<HTMLDivElement>>

Guides: Preview & playback, Overview, Preview, Transform box

ScrubberCopy Anchor Link

Unstyled seek bar parts: <Scrubber.Root> with <Scrubber.Range> and <Scrubber.Thumb> inside.

const Scrubber: {
    Root: react.ForwardRefExoticComponent<ScrubberRootProps & react.RefAttributes<HTMLDivElement>>;
    Range: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
        children?: ReactNode;
    } & react.RefAttributes<HTMLDivElement>>;
    Thumb: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
        children?: ReactNode;
    } & react.RefAttributes<HTMLDivElement>>;
}

Guides: Overview, Preview, Scrubber, React

TimelineCopy Anchor Link

Unstyled timeline parts. See the module comment for the structure.

const Timeline: {
    Root: react.ForwardRefExoticComponent<TimelineRootProps & react.RefAttributes<HTMLDivElement>>;
    Viewport: react.ForwardRefExoticComponent<TimelineViewportProps & react.RefAttributes<HTMLDivElement>>;
    Ruler: react.ForwardRefExoticComponent<TimelineRulerProps & react.RefAttributes<HTMLDivElement>>;
    Track: react.ForwardRefExoticComponent<TimelineTrackProps & react.RefAttributes<HTMLDivElement>>;
    TrackHeader: react.ForwardRefExoticComponent<DivProps & {
        children?: ReactNode;
    } & react.RefAttributes<HTMLDivElement>>;
    Lane: react.ForwardRefExoticComponent<Time …

Guides: Timeline, Overview, Scrubber, Timeline

TransformBoxCopy Anchor Link

Unstyled transform-box parts for the preview. See the module comment for the structure.

const TransformBox: {
    Root: react.ForwardRefExoticComponent<TransformBoxRootProps & react.RefAttributes<HTMLDivElement>>;
    Outline: typeof Outline;
    Guides: typeof Guides;
    Body: typeof Body;
    Handle: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
        children?: ReactNode;
    } & {
        corner: 0 | 1 | 2 | 3;
    } & react.RefAttributes<HTMLDivElement>>;
    RotateHandle: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
        children?: ReactNode;
    } & {
        distance?: number;
    } & react.RefAttributes<HTM …

Guides: Selection & canvas editing, Overview, Preview, Transform box

WaveformCopy Anchor Link

Mirrored waveform bars for a media range, filling the canvas's CSS box. Bars use currentColor, so the text color styles them. Redraws on resize and when its inputs change; the backing store is capped so very wide clips at high zoom stay within mobile memory limits.

const Waveform: react.ForwardRefExoticComponent<WaveformProps & react.RefAttributes<HTMLCanvasElement>>

Guides: Timeline, Overview, Timeline, Waveform

InterfacesCopy Anchor Link

PlaybackProviderPropsCopy Anchor Link

PlaybackValueCopy Anchor Link

PlayheadFollowCopy Anchor Link

Guides: Timeline, React

PreviewPropsCopy Anchor Link

Extends Omit<HTMLAttributes<HTMLDivElement>, "children">.

PreviewStateCopy Anchor Link

ProjectSessionCopy Anchor Link

Guides: MCP server

RulerTickCopy Anchor Link

ScrubberRootPropsCopy Anchor Link

Extends DivProps.

SessionInitCopy Anchor Link

TimelineClipPropsCopy Anchor Link

Extends DivProps.

TimelineClipStateCopy Anchor Link

TimelineContextValueCopy Anchor Link

TimelineCutCopy Anchor Link

Extends TrackCut.

TimelineCutsPropsCopy Anchor Link

TimelineLanePropsCopy Anchor Link

Extends DivProps.

TimelineRootPropsCopy Anchor Link

Extends DivProps.

TimelineRulerPropsCopy Anchor Link

Extends DivProps.

TimelineTrackPropsCopy Anchor Link

Extends DivProps.

TimelineTrimHandlePropsCopy Anchor Link

Extends DivProps.

TimelineViewportPropsCopy Anchor Link

Extends DivProps.

TimelineZoomOptionsCopy Anchor Link

TransformBoxOutlinePropsCopy Anchor Link

Extends SVGProps<SVGPolygonElement>.

TransformBoxRootPropsCopy Anchor Link

Extends Omit<HTMLAttributes<HTMLDivElement>, "children">.

TransformBoxStateCopy Anchor Link

UndoRedoCopy Anchor Link

WaveformPropsCopy Anchor Link

Extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, "children">.

TypesCopy Anchor Link

ProjectProviderPropsCopy Anchor Link

type ProjectProviderProps = {
    init: ProjectSettings | ProjectDocument;
    seed?: (project: Project) => void;
    project?: never;
    children: ReactNode;
} | {
    project: Project;
    init?: never;
    seed?: never;
    children: ReactNode;
};