@mcut/compositor 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,507 @@
+import { AssetId, BlendMode, CaptionStyle, Effect, Project, TextBox, TextRun, TextStyle, TimelineElement, Track, Transform, TransitionPair } from "@mcut/timeline";
+
+//#region src/geometry.d.ts
+/**
+ * Element coordinates are center-origin: (0, 0) is the canvas center and the
+ * element is anchored at its own center. This converts to canvas pixels.
+ */
+declare function toCanvasPoint(project: Project, x: number, y: number): {
+  x: number;
+  y: number;
+};
+declare function fromCanvasPoint(project: Project, x: number, y: number): {
+  x: number;
+  y: number;
+};
+/** Oriented bounding box in canvas pixels. Rotation in degrees, clockwise. */
+interface OBB {
+  cx: number;
+  cy: number;
+  width: number;
+  height: number;
+  rotation: number;
+}
+interface ElementSize {
+  width: number;
+  height: number;
+}
+declare const degToRad: (deg: number) => number;
+interface SizeHelpers {
+  /** Natural pixel size of a media asset (probed metadata). */
+  getAssetSize?: (assetId: string) => ElementSize | null;
+  /** Measure a text block (unscaled). Required for text element bounds. */
+  measureText?: (text: string, style: TextStyle, box?: TextBox, runs?: readonly TextRun[]) => ElementSize;
+}
+declare function getElementNaturalSize(element: TimelineElement, helpers?: SizeHelpers): ElementSize | null;
+declare function getElementDisplaySize(element: TimelineElement, helpers?: SizeHelpers): ElementSize | null;
+interface DisplaySizePatch {
+  width?: number;
+  height?: number;
+  preserveAspect?: boolean;
+}
+declare function getTransformForDisplaySize(transform: Transform, natural: ElementSize, patch: DisplaySizePatch): Transform;
+/**
+ * The element's oriented bounding box on the canvas, or `null` when its size
+ * is unknown (e.g. unprobed media without a frame yet). Captions are
+ * positioned by their style band and are not transformable; they have no OBB.
+ */
+declare function getElementOBB(project: Project, element: TimelineElement, helpers?: SizeHelpers): OBB | null;
+/** Is the canvas-space point inside the (rotated) box? */
+declare function hitTestOBB(obb: OBB, x: number, y: number): boolean;
+type HandleId = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'rotate';
+interface Handle {
+  id: HandleId;
+  /** Canvas-space position. */
+  x: number;
+  y: number;
+}
+/** Distance of the rotate handle above the box's top edge (canvas px). */
+declare const ROTATE_HANDLE_OFFSET = 32;
+/** The 8 resize handles plus the rotate handle, in canvas space. */
+declare function getHandles(obb: OBB): Handle[];
+/** Hit-test the handles (square hit area of `size` px around each). */
+declare function hitTestHandles(obb: OBB, x: number, y: number, size?: number): HandleId | null;
+/**
+ * "Contain" scale factor for fitting a `width`×`height` media into the
+ * project frame (used when inserting media elements).
+ */
+declare function getFitScale(project: Project, width: number, height: number): number;
+//#endregion
+//#region src/types.d.ts
+/** A 2D context we can composite into (on- or off-screen). */
+type Canvas2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * Supplies pixel data for media assets at a given source time. The preview
+ * implementation is allowed to be approximate (pooled `<video>` elements);
+ * the export implementation must be exact (decoded samples). Keeping this
+ * behind an interface is what lets one compositor serve both.
+ */
+interface FrameSource {
+  /**
+   * Image for `assetId` at `sourceTimeMs` (media-local time, after trim).
+   * Return `null` when no frame is available yet; the compositor skips it.
+   */
+  getFrame(assetId: AssetId, sourceTimeMs: number): CanvasImageSource | null;
+}
+interface RenderFrameOptions {
+  /** Pixel source for video/image assets. Omit to render only vector elements. */
+  source?: FrameSource;
+  /** Canvas background. Default black. */
+  backgroundColor?: string;
+  /**
+   * Elements to leave out of the frame — e.g. a text element while a DOM
+   * inline editor is overlaid on it (the editor IS its WYSIWYG render).
+   */
+  skipElementIds?: ReadonlySet<string>;
+  /**
+   * Sub-frame passes for per-element motion blur (see `motion-blur.ts`).
+   * Default 8; export passes 16.
+   */
+  motionBlurSamples?: number;
+  /**
+   * Scratch surface factory for motion-blur accumulation; the context is
+   * cleared before each use. Defaults to a cached `OffscreenCanvas` —
+   * environments without one (and tests) inject this. Return null to
+   * disable motion blur.
+   */
+  createScratchContext?: (width: number, height: number) => Canvas2D | null;
+}
+interface ElementRenderContext {
+  /**
+   * Frame-space canvas2d context for raster drawing (text, chrome, custom
+   * renderers). On the canvas2d backend this is the target itself; on GPU
+   * backends it is a scratch surface composited in z-order. Reading it marks
+   * the raster surface in use — renderers with a structured fast path (video
+   * /image quads) should draw via `backend` instead.
+   */
+  ctx: Canvas2D;
+  /** The draw layer (see backend.ts) — structured fast paths live here. */
+  backend: RenderBackend;
+  project: Project;
+  track: Track;
+  /** Absolute timeline time being rendered. */
+  timeMs: number;
+  source: FrameSource | undefined;
+}
+type ElementRenderer<E extends TimelineElement = TimelineElement> = (element: E, context: ElementRenderContext) => void;
+//#endregion
+//#region src/backend.d.ts
+/**
+ * The draw layer renderFrame composites through. The track/element walk,
+ * transition pairing, and geometry in render-frame.ts are renderer-agnostic;
+ * backends own how pixels actually land:
+ *
+ *  - {@link Canvas2DBackend} — the original canvas2d path. The reference
+ *    implementation: tests run against it (FakeContext2D), and headless/Node
+ *    environments use it. Not a runtime fallback once WebGPU is the default.
+ *  - WebGPUBackend (webgpu/) — image quads composite as textured passes with
+ *    WGSL effects; raster content (text, captions, multicam chrome, custom
+ *    renderers) still paints through canvas2d in frame space and uploads as
+ *    a texture layer, preserving output across backends.
+ *
+ * Determinism contract: for a given backend, the same project, time, and
+ * frame source produce the same pixels in preview and export. Across
+ * backends, output is perceptually identical (GPU float math differs at the
+ * ULP level), so golden tests compare with tolerance, not byte equality.
+ */
+/** Resolved element chrome: transform in frame coords + compositing state. */
+interface LayerChrome {
+  /** Element center in canvas coordinates. */
+  centerX: number;
+  centerY: number;
+  rotationDeg: number;
+  scaleX: number;
+  scaleY: number;
+  /** 0..1, multiplied into the layer. */
+  opacity: number;
+  blendMode?: BlendMode | undefined;
+  effects?: readonly Effect[] | undefined;
+}
+/** A plain media draw: one image into a centered rect, optional crop/radius. */
+interface ImageQuad {
+  image: CanvasImageSource;
+  /** Source crop rect in image pixels; null draws the whole image. */
+  src: {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+  } | null;
+  /** Destination size, centered on the chrome's origin. */
+  dw: number;
+  dh: number;
+  /** Rounded-corner radius in destination pixels (0 = sharp). */
+  cornerRadius: number;
+}
+interface RenderBackend {
+  readonly kind: 'canvas2d' | 'webgpu' | (string & {});
+  readonly width: number;
+  readonly height: number;
+  beginFrame(backgroundColor: string): void;
+  endFrame(): void;
+  /**
+   * The frame-space canvas2d context for raster content. Acquiring it marks
+   * the raster surface dirty so the backend composites it in z-order;
+   * renderers that only need it for text measurement still go through here
+   * (text rasterizes anyway).
+   */
+  acquireRaster(): Canvas2D;
+  /**
+   * Composite a media quad with chrome — the GPU fast path. Backends without
+   * one (or layers a backend cannot run, e.g. raw `css` filters on WebGPU)
+   * draw it through the raster context instead.
+   */
+  drawImageQuad(quad: ImageQuad, chrome: LayerChrome): void;
+  /**
+   * While a raster scope is open, every draw — including image quads — lands
+   * on the raster context, so canvas2d state (clips, alpha, transforms) set
+   * by the caller applies. Transition mixes and motion-blur accumulation
+   * need this. Scopes nest.
+   */
+  pushRasterScope(): void;
+  popRasterScope(): void;
+}
+/**
+ * Transform + opacity + effect-stack filter + blend mode around a canvas2d
+ * draw (the original withTransform). `ctx.filter` is unsupported in some
+ * older engines; there the stack degrades to an unfiltered render rather
+ * than failing.
+ */
+declare function applyChrome(ctx: Canvas2D, chrome: LayerChrome, draw: () => void): void;
+/** Draw an {@link ImageQuad} in local (chrome-applied) coordinates. */
+declare function drawImageQuad2D(ctx: Canvas2D, quad: ImageQuad): void;
+/** The canvas2d backend: draws straight into the target context. */
+declare class Canvas2DBackend implements RenderBackend {
+  private readonly ctx;
+  readonly width: number;
+  readonly height: number;
+  readonly kind = "canvas2d";
+  constructor(ctx: Canvas2D, width: number, height: number);
+  beginFrame(backgroundColor: string): void;
+  endFrame(): void;
+  acquireRaster(): Canvas2D;
+  drawImageQuad(quad: ImageQuad, chrome: LayerChrome): void;
+  pushRasterScope(): void;
+  popRasterScope(): void;
+}
+/**
+ * Build the per-element render context. `ctx` is a getter so backends learn
+ * when raster content is actually being drawn (GPU backends flush the
+ * raster surface lazily, in z-order).
+ */
+declare function createElementContext(backend: RenderBackend, project: Project, track: Track, timeMs: number, source: FrameSource | undefined): ElementRenderContext;
+//#endregion
+//#region src/render-frame.d.ts
+/**
+ * Render one frame of `project` at `timeMs` into `ctx` (canvas2d path).
+ *
+ * Pure with respect to inputs: the same project, time, and frame source
+ * produce the same pixels — which is what makes the export path
+ * deterministic. The context is expected to be in project coordinates
+ * (`project.width` × `project.height`); callers rendering at other sizes
+ * apply their own transform before calling.
+ */
+declare function renderFrame(ctx: Canvas2D, project: Project, timeMs: number, options?: RenderFrameOptions): void;
+/**
+ * Render one frame through an explicit {@link RenderBackend}. The
+ * track/element walk, transition pairing, and animation resolution here are
+ * backend-agnostic; only the draws differ.
+ *
+ * Tracks render bottom-up (index 0 first), elements in start order. Clips
+ * joined by a transition render through the blend instead of the normal
+ * pass while the window (centered on their cut) is active.
+ */
+declare function renderFrameWith(backend: RenderBackend, project: Project, timeMs: number, options?: RenderFrameOptions): void;
+//#endregion
+//#region src/gpu-effects.d.ts
+/** Idempotent; the compositor registers these at module load. */
+declare function registerGpuEffectTypes(): void;
+//#endregion
+//#region src/webgpu/webgpu-backend.d.ts
+/**
+ * The WebGPU compositor backend. Image quads (video/image elements)
+ * composite as full-frame passes over a ping-pong texture pair —
+ * `importExternalTexture` keeps `VideoFrame`s zero-copy — with effects as
+ * WGSL passes and every blend mode in one shader (mode uniform). Raster
+ * content (text, captions, multicam chrome, transitions, custom renderers)
+ * still paints through canvas2d in frame space and uploads as a texture
+ * layer in z-order, so output matches the reference Canvas2D backend.
+ *
+ * Lifecycle: `WebGPUBackend.create({ canvas, width, height })` once, then
+ * `renderFrameWith(backend, project, timeMs, options)` per frame, `resize`
+ * on project dimension changes, `dispose` when done. For export, pass the
+ * GPUTexture-backed canvas straight to Mediabunny's CanvasSource — no CPU
+ * readback.
+ */
+interface WebGPUBackendOptions {
+  /** Presentation canvas; the backend configures its 'webgpu' context. */
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+  /** Project (composition) size — passes render at this resolution. */
+  width: number;
+  height: number;
+  /** Bring your own device (tests/sharing); otherwise adapter-requested. */
+  device?: GPUDevice;
+}
+/** Whether this runtime exposes WebGPU at all (Chrome 113+/Safari 26+/Firefox 141+). */
+declare function isWebGPUSupported(): boolean;
+declare class WebGPUBackend implements RenderBackend {
+  readonly kind = "webgpu";
+  readonly width: number;
+  readonly height: number;
+  private readonly device;
+  private readonly context;
+  private readonly presentationFormat;
+  private acc;
+  private accIndex;
+  private readonly rasterCanvas;
+  private readonly rasterCtx;
+  private rasterDirty;
+  private rasterScope;
+  private readonly sampler;
+  private readonly pipelines;
+  private readonly texturePool;
+  private frameBuffers;
+  private readonly identityCurves;
+  private readonly luts;
+  static create(options: WebGPUBackendOptions): Promise<WebGPUBackend>;
+  private constructor();
+  /**
+   * Register a 3D LUT for `lut3d` effects: `data` is size³ RGB triples
+   * (0..1, red fastest), flattened to a (size² × size) 2D texture.
+   */
+  registerLut3D(lutId: string, size: number, data: Float32Array): void;
+  beginFrame(backgroundColor: string): void;
+  endFrame(): void;
+  acquireRaster(): Canvas2D;
+  pushRasterScope(): void;
+  popRasterScope(): void;
+  drawImageQuad(quad: ImageQuad, chrome: LayerChrome): void;
+  /** Free GPU resources. The backend is unusable afterwards. */
+  dispose(): void;
+  private createAccTexture;
+  private acquireTexture;
+  private releaseTexture;
+  private uniformBuffer;
+  private storageBuffer;
+  /** Upload the raster scratch and composite it as a normal full-frame layer. */
+  private flushRaster;
+  private drawQuadOnGpu;
+  /** Sample (and crop) the source into a fresh layer texture. */
+  private prepareLayer;
+  private runEffectPass;
+  private runColorPass;
+  private runBlurPasses;
+  private compositeFullFrame;
+  private renderFullscreen;
+}
+//#endregion
+//#region src/webgpu/effect-plan.d.ts
+interface ColorOp {
+  kind: number;
+  /** Up to 8 packed params, op-specific (vec4 a + vec4 b in the shader). */
+  params: number[];
+}
+type EffectPass = {
+  kind: 'color';
+  ops: ColorOp[]; /** Per-channel 256-entry LUTs when a curves op is in this run. */
+  curves: {
+    r: Float32Array;
+    g: Float32Array;
+    b: Float32Array;
+  } | null;
+} | {
+  kind: 'blur';
+  radius: number;
+} | {
+  kind: 'shadow';
+  offsetX: number;
+  offsetY: number;
+  blur: number;
+  color: [number, number, number, number];
+} | {
+  kind: 'lut3d';
+  lutId: string;
+  intensity: number;
+};
+interface EffectPlan {
+  passes: EffectPass[];
+  /** The stack contains effects only canvas2d can run (`css`/unknown). */
+  unsupported: boolean;
+}
+interface CurvePoint {
+  x: number;
+  y: number;
+}
+/** Monotone-x piecewise-linear curve → 256-entry LUT (identity when empty). */
+declare function curveToLut(points: readonly CurvePoint[] | undefined): Float32Array;
+declare function planEffects(effects: readonly Effect[] | undefined): EffectPlan;
+/** True when this stack can only render through the canvas2d raster path. */
+declare function hasUnsupportedEffects(effects: readonly Effect[] | undefined): boolean;
+//#endregion
+//#region src/transition-renderers.d.ts
+/**
+ * The renderer half of the transition registry (pair it with
+ * registerTransitionType in @mcut/timeline). A transition is a pure mixer:
+ * given draw thunks for both sides of a cut and the blend completion, paint
+ * the in-between frame. The same renderers serve clip-to-clip transitions
+ * (render-frame.ts) and multicam angle-cut transitions (renderers.ts).
+ */
+/** Everything a transition renderer needs to blend its pair. */
+interface TransitionRenderContext {
+  ctx: Canvas2D;
+  project: Project;
+  pair: TransitionPair;
+  timeMs: number;
+  /** Blend completion 0→1 across the window (0.5 at the cut). */
+  completion: number;
+  /** Draw the outgoing clip (already extended past its out point). */
+  drawLeft: () => void;
+  /** Draw the incoming clip (already pre-rolling before its in point). */
+  drawRight: () => void;
+}
+type TransitionRenderer = (context: TransitionRenderContext) => void;
+/**
+ * Register the renderer half of a transition type. Built-ins register below
+ * through the same call; re-registering overrides (e.g. to restyle a
+ * built-in wipe).
+ */
+declare function registerTransitionRenderer(type: string, renderer: TransitionRenderer): void;
+/** The registered renderer for `type`, or undefined (degrade to a hard cut). */
+declare function getTransitionRenderer(type: string): TransitionRenderer | undefined;
+//#endregion
+//#region src/text.d.ts
+/**
+ * Width of `text` drawn with `font` and `letterSpacingPx` of tracking.
+ * Implementations should set `ctx.letterSpacing` when the engine supports it
+ * so measurement matches drawing; engines without it ignore the parameter
+ * (and the renderer draws without tracking — consistent both ways).
+ */
+type MeasureFn = (text: string, font: string, letterSpacingPx?: number) => number;
+declare function buildFont(style: {
+  fontStyle?: 'normal' | 'italic';
+  fontWeight: number;
+  fontSize: number;
+  fontFamily: string;
+}): string;
+/** Render-time case transform; the stored text keeps the user's casing. */
+declare function applyTextTransform(text: string, transform: TextStyle['textTransform']): string;
+/** One same-style stretch of a visual line (rich-text runs; see rich-text.ts). */
+interface TextSegment {
+  /** Case-transformed slice, ready to paint. */
+  text: string;
+  width: number;
+  font: string;
+  /** Fill override from the segment's run (base style color otherwise). */
+  color?: string;
+}
+interface TextBlockLayout {
+  /** `segments` present only when the element has style runs. */
+  lines: {
+    text: string;
+    width: number;
+    segments?: TextSegment[];
+  }[];
+  font: string;
+  lineHeight: number;
+  padding: number;
+  overflow: TextBox['overflow'] | null;
+  /** Box size including padding — matches what the renderer draws. */
+  width: number;
+  height: number;
+}
+interface TextBlockOptions {
+  box?: TextBox;
+  /** Per-range style overrides (character offsets into the text). */
+  runs?: readonly TextRun[];
+}
+/**
+ * Lay out a (possibly multi-line) text element. Lines come from explicit
+ * newlines only unless a text box width is provided.
+ */
+declare function layoutTextBlock(measure: MeasureFn, text: string, style: TextStyle, options?: TextBlockOptions): TextBlockLayout;
+interface CaptionWordBox {
+  text: string;
+  /** X offset from the line's left edge. */
+  x: number;
+  width: number;
+  /** Word timing relative to the element start, when known. */
+  startMs?: number;
+  endMs?: number;
+}
+interface CaptionLayout {
+  lines: {
+    words: CaptionWordBox[];
+    width: number;
+  }[];
+  font: string;
+  lineHeight: number;
+  spaceWidth: number;
+}
+/**
+ * Greedily wrap caption words into centered lines no wider than `maxWidth`.
+ * Falls back to whitespace-split text when word timings are absent.
+ */
+declare function layoutCaption(measure: MeasureFn, element: {
+  text: string;
+  words?: {
+    text: string;
+    startMs: number;
+    endMs: number;
+  }[];
+}, style: CaptionStyle, maxWidth: number): CaptionLayout;
+//#endregion
+//#region src/renderers.d.ts
+/**
+ * Register a renderer for an element type. Built-in types can be overridden;
+ * custom element types (added via custom commands) plug in here — the
+ * compositor side of the engine's command registry.
+ */
+declare function registerElementRenderer<E extends TimelineElement>(type: E['type'] | (string & {}), renderer: ElementRenderer<E>): void;
+declare function getElementRenderer(type: string): ElementRenderer | undefined;
+declare function measureWith(ctx: Canvas2D): MeasureFn;
+declare function getImageSize(source: CanvasImageSource): {
+  width: number;
+  height: number;
+};
+//#endregion
+export { type Canvas2D, Canvas2DBackend, type CaptionLayout, type CaptionWordBox, type ColorOp, type DisplaySizePatch, type EffectPass, type EffectPlan, type ElementRenderContext, type ElementRenderer, type ElementSize, type FrameSource, type Handle, type HandleId, type ImageQuad, type LayerChrome, type MeasureFn, type OBB, ROTATE_HANDLE_OFFSET, type RenderBackend, type RenderFrameOptions, type SizeHelpers, type TextBlockLayout, type TransitionRenderContext, type TransitionRenderer, WebGPUBackend, type WebGPUBackendOptions, applyChrome, applyTextTransform, buildFont, createElementContext, curveToLut, degToRad, drawImageQuad2D, fromCanvasPoint, getElementDisplaySize, getElementNaturalSize, getElementOBB, getElementRenderer, getFitScale, getHandles, getImageSize, getTransformForDisplaySize, getTransitionRenderer, hasUnsupportedEffects, hitTestHandles, hitTestOBB, isWebGPUSupported, layoutCaption, layoutTextBlock, measureWith, planEffects, registerElementRenderer, registerGpuEffectTypes, registerTransitionRenderer, renderFrame, renderFrameWith, toCanvasPoint };