@mcut/react 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,187 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic,
+verbal, or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists,
+source code control systems, and issue tracking systems that are managed by,
+or on behalf of, the Licensor for the purpose of discussing and improving the
+Work, but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed
+by their Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You institute
+patent litigation against any entity (including a cross-claim or counterclaim
+in a lawsuit) alleging that the Work or a Contribution incorporated within
+the Work constitutes direct or contributory patent infringement, then any
+patent licenses granted to You under this License for that Work shall
+terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a
+copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do
+not modify the License. You may add Your own attribution notices within
+Derivative Works that You distribute, alongside or as an addendum to the
+NOTICE text from the Work, provided that such additional attribution notices
+cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated in
+this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the
+Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to
+in writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability
+to use the Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of
+the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,11 @@
+# @mcut/react
+
+React bindings for mcut.
+
+```sh
+bun add @mcut/react react react-dom
+```
+
+This package provides the editor provider, hooks, canvas player binding,
+selection overlay, playback clock, and audio preview integration for React apps.
+React and React DOM are peer dependencies.

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { ReactNode } from "react";
+import { PreviewMediaPool } from "@mcut/media";
+import { EditorEngine, EditorState, ElementId, ElementLocation, PlaybackState, Project, SelectionState, Transform } from "@mcut/timeline";
+import { HandleId, OBB } from "@mcut/compositor";
+
+//#region src/context.d.ts
+interface EditorContextValue {
+  engine: EditorEngine;
+  pool: PreviewMediaPool;
+}
+interface EditorProviderProps {
+  /** Bring your own engine (e.g. created outside React); otherwise one is created. */
+  engine?: EditorEngine;
+  /** Initial project for the internally-created engine. */
+  project?: Project;
+  maxHistorySize?: number;
+  children: ReactNode;
+}
+/**
+ * Provides the editor engine and the preview media pool to the component
+ * tree. All mcut UI (PlayerCanvas, timeline panels, ...) lives under this.
+ */
+declare function EditorProvider({
+  engine: externalEngine,
+  project,
+  maxHistorySize,
+  children
+}: EditorProviderProps): import("react").JSX.Element;
+declare function useEditorContext(): EditorContextValue;
+//#endregion
+//#region src/hooks.d.ts
+/** The editor engine: dispatch commands, undo/redo, transport. */
+declare function useEditor(): EditorEngine;
+/** Subscribe to a slice of editor state (project, selection, history flags). */
+declare function useEditorState<TSelected = EditorState>(selector?: (state: EditorState) => TSelected, compare?: (a: TSelected, b: TSelected) => boolean): TSelected;
+/** Subscribe to a slice of playback state (time, playing, volume). */
+declare function usePlayback<TSelected = PlaybackState>(selector?: (state: PlaybackState) => TSelected, compare?: (a: TSelected, b: TSelected) => boolean): TSelected;
+declare function useProject(): Project;
+declare function useSelection(): SelectionState;
+/** The first selected element with its track, if any. */
+declare function useSelectedElement(): ElementLocation | undefined;
+//#endregion
+//#region src/player-canvas.d.ts
+/**
+ * Preview raster resolution. `'auto'` renders at the displayed size,
+ * a number caps the project's short side (720 ≈ 720p), `'full'` always
+ * rasters at full project resolution. Every mode is capped at project
+ * resolution — CSS scales the canvas to fit either way.
+ */
+type PreviewQuality = 'auto' | 'full' | number;
+interface PlayerCanvasProps {
+  className?: string;
+  /** Enable canvas selection/move/resize/rotate. Default true. */
+  interactive?: boolean;
+  /** Project background color. Default black. */
+  background?: string;
+  /**
+   * Elements left out of the render — e.g. a text element while a DOM
+   * inline editor overlays it (renderFrame's skipElementIds).
+   */
+  hiddenElementIds?: ReadonlySet<string>;
+  /** Double-click on an element (topmost hit). Hosts use it to open editors. */
+  onElementDoubleClick?: (elementId: ElementId) => void;
+  /**
+   * Preview raster resolution; `'auto'` (default) matches the displayed
+   * size. A 4K project in an ~800px pane rasters ~20× fewer pixels per
+   * frame than `'full'`, which is usually the difference between smooth
+   * and dropped playback on big projects.
+   */
+  quality?: PreviewQuality;
+  /**
+   * Compositor backend. `'webgpu'` renders through the WebGPU pass
+   * pipeline (requires `navigator.gpu`; falls back to canvas2d while the
+   * device initializes or when unavailable). Default `'canvas2d'`.
+   */
+  renderer?: 'canvas2d' | 'webgpu';
+}
+declare function PlayerCanvas({
+  className,
+  interactive,
+  background,
+  quality,
+  hiddenElementIds,
+  onElementDoubleClick,
+  renderer
+}: PlayerCanvasProps): import("react").JSX.Element;
+//#endregion
+//#region src/gestures.d.ts
+interface GesturePoint {
+  x: number;
+  y: number;
+}
+interface BoxResizeResult {
+  transform: Transform;
+  displayWidth: number;
+  displayHeight: number;
+}
+/** Translate gesture: offset the base transform by the pointer delta. */
+declare function applyMove(base: Transform, start: GesturePoint, current: GesturePoint): Transform;
+/** Rotate gesture around the element center. */
+declare function applyRotate(base: Transform, obb: OBB, start: GesturePoint, current: GesturePoint): Transform;
+/**
+ * Resize gesture. Corner handles scale uniformly; edge handles scale one
+ * axis. Pointer positions are mapped into the element's local (un-rotated)
+ * space so resizing behaves intuitively on rotated elements.
+ */
+declare function applyResize(base: Transform, obb: OBB, handle: Exclude<HandleId, 'rotate'>, start: GesturePoint, current: GesturePoint): Transform;
+declare function applyBoxResize(base: Transform, obb: OBB, handle: Exclude<HandleId, 'rotate'>, current: GesturePoint, minSize?: number): BoxResizeResult;
+//#endregion
+export { type BoxResizeResult, type EditorContextValue, EditorProvider, type EditorProviderProps, type GesturePoint, PlayerCanvas, type PlayerCanvasProps, type PreviewQuality, applyBoxResize, applyMove, applyResize, applyRotate, useEditor, useEditorContext, useEditorState, usePlayback, useProject, useSelectedElement, useSelection };

package/dist/index.js

@@ -0,0 +1,681 @@
+"use client";
+import { createContext, useContext, useEffect, useRef } from "react";
+import { PreviewMediaPool, getActiveMediaItems } from "@mcut/media";
+import { EditorEngine, getElement, getElementLocation, getProjectDurationMs, hasKeyframes, isElementActiveAt, resolveAnimatedElement } from "@mcut/timeline";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useSelector } from "@tanstack/react-store";
+import { WebGPUBackend, degToRad, getElementOBB, getHandles, hitTestHandles, hitTestOBB, isWebGPUSupported, layoutTextBlock, measureWith, renderFrame, renderFrameWith } from "@mcut/compositor";
+//#region src/context.tsx
+const EditorContext = createContext(null);
+/**
+* Provides the editor engine and the preview media pool to the component
+* tree. All mcut UI (PlayerCanvas, timeline panels, ...) lives under this.
+*/
+function EditorProvider({ engine: externalEngine, project, maxHistorySize, children }) {
+	const valueRef = useRef(null);
+	if (valueRef.current === null) {
+		const engine = externalEngine ?? new EditorEngine({
+			...project ? { project } : {},
+			...maxHistorySize !== void 0 ? { maxHistorySize } : {}
+		});
+		valueRef.current = {
+			engine,
+			pool: new PreviewMediaPool((assetId) => engine.project.assets[assetId])
+		};
+	}
+	useEffect(() => {
+		const value = valueRef.current;
+		return () => {
+			value?.pool.dispose();
+		};
+	}, []);
+	return /* @__PURE__ */ jsx(EditorContext.Provider, {
+		value: valueRef.current,
+		children
+	});
+}
+function useEditorContext() {
+	const context = useContext(EditorContext);
+	if (!context) throw new Error("mcut hooks must be used inside <EditorProvider>");
+	return context;
+}
+//#endregion
+//#region src/hooks.ts
+/** The editor engine: dispatch commands, undo/redo, transport. */
+function useEditor() {
+	return useEditorContext().engine;
+}
+/** Subscribe to a slice of editor state (project, selection, history flags). */
+function useEditorState(selector, compare) {
+	const { engine } = useEditorContext();
+	return useSelector(engine.store, selector, compare ? { compare } : void 0);
+}
+/** Subscribe to a slice of playback state (time, playing, volume). */
+function usePlayback(selector, compare) {
+	const { engine } = useEditorContext();
+	return useSelector(engine.playback, selector, compare ? { compare } : void 0);
+}
+function useProject() {
+	return useEditorState((state) => state.project);
+}
+function useSelection() {
+	return useEditorState((state) => state.selection);
+}
+/** The first selected element with its track, if any. */
+function useSelectedElement() {
+	return useEditorState((state) => {
+		const id = state.selection.elementIds[0];
+		return id ? getElementLocation(state.project, id) : void 0;
+	}, (a, b) => a?.element === b?.element && a?.track === b?.track && a?.trackIndex === b?.trackIndex);
+}
+//#endregion
+//#region src/gestures.ts
+const MIN_SCALE = .05;
+const MIN_BOX_SIZE = 8;
+/** Keep magnitude ≥ MIN_SCALE, preserving sign (negative scale = flip). */
+const clampScale = (value) => {
+	return (value < 0 ? -1 : 1) * Math.max(MIN_SCALE, Math.abs(value));
+};
+function pointToLocal(obb, point) {
+	const rad = degToRad(-obb.rotation);
+	const dx = point.x - obb.cx;
+	const dy = point.y - obb.cy;
+	return {
+		x: dx * Math.cos(rad) - dy * Math.sin(rad),
+		y: dx * Math.sin(rad) + dy * Math.cos(rad)
+	};
+}
+function localDeltaToCanvas(obb, delta) {
+	const rad = degToRad(obb.rotation);
+	return {
+		x: delta.x * Math.cos(rad) - delta.y * Math.sin(rad),
+		y: delta.x * Math.sin(rad) + delta.y * Math.cos(rad)
+	};
+}
+/** Translate gesture: offset the base transform by the pointer delta. */
+function applyMove(base, start, current) {
+	return {
+		...base,
+		x: Math.round(base.x + (current.x - start.x)),
+		y: Math.round(base.y + (current.y - start.y))
+	};
+}
+/** Rotate gesture around the element center. */
+function applyRotate(base, obb, start, current) {
+	const startAngle = Math.atan2(start.y - obb.cy, start.x - obb.cx);
+	const currentAngle = Math.atan2(current.y - obb.cy, current.x - obb.cx);
+	let rotation = base.rotation + (currentAngle - startAngle) * 180 / Math.PI;
+	rotation = ((rotation + 180) % 360 + 360) % 360 - 180;
+	return {
+		...base,
+		rotation: Math.round(rotation * 10) / 10
+	};
+}
+/**
+* Resize gesture. Corner handles scale uniformly; edge handles scale one
+* axis. Pointer positions are mapped into the element's local (un-rotated)
+* space so resizing behaves intuitively on rotated elements.
+*/
+function applyResize(base, obb, handle, start, current) {
+	const localStart = pointToLocal(obb, start);
+	const localCurrent = pointToLocal(obb, current);
+	if (handle === "e" || handle === "w") {
+		const factor = localStart.x === 0 ? 1 : localCurrent.x / localStart.x;
+		return {
+			...base,
+			scaleX: clampScale(base.scaleX * factor)
+		};
+	}
+	if (handle === "n" || handle === "s") {
+		const factor = localStart.y === 0 ? 1 : localCurrent.y / localStart.y;
+		return {
+			...base,
+			scaleY: clampScale(base.scaleY * factor)
+		};
+	}
+	const startDistance = Math.hypot(localStart.x, localStart.y);
+	const factor = startDistance === 0 ? 1 : Math.hypot(localCurrent.x, localCurrent.y) / startDistance;
+	return {
+		...base,
+		scaleX: clampScale(base.scaleX * factor),
+		scaleY: clampScale(base.scaleY * factor)
+	};
+}
+function applyBoxResize(base, obb, handle, current, minSize = MIN_BOX_SIZE) {
+	const localCurrent = pointToLocal(obb, current);
+	let left = -obb.width / 2;
+	let right = obb.width / 2;
+	let top = -obb.height / 2;
+	let bottom = obb.height / 2;
+	if (handle.includes("w")) left = localCurrent.x;
+	if (handle.includes("e")) right = localCurrent.x;
+	if (handle.includes("n")) top = localCurrent.y;
+	if (handle.includes("s")) bottom = localCurrent.y;
+	if (right - left < minSize) if (handle.includes("w")) left = right - minSize;
+	else right = left + minSize;
+	if (bottom - top < minSize) if (handle.includes("n")) top = bottom - minSize;
+	else bottom = top + minSize;
+	const centerDelta = localDeltaToCanvas(obb, {
+		x: (left + right) / 2,
+		y: (top + bottom) / 2
+	});
+	return {
+		transform: {
+			...base,
+			x: Math.round((base.x + centerDelta.x) * 10) / 10,
+			y: Math.round((base.y + centerDelta.y) * 10) / 10
+		},
+		displayWidth: Math.round((right - left) * 10) / 10,
+		displayHeight: Math.round((bottom - top) * 10) / 10
+	};
+}
+//#endregion
+//#region src/player-canvas.tsx
+/** Snap-to-center threshold in screen px while moving an element. */
+const CENTER_SNAP_PX = 10;
+const GESTURE_PROPERTIES = [
+	["position.x", "x"],
+	["position.y", "y"],
+	["scale.x", "scaleX"],
+	["scale.y", "scaleY"],
+	["rotation", "rotation"]
+];
+/**
+* Apply a gesture's transform: armed properties (Premiere stopwatch on)
+* auto-key at the playhead; unarmed properties patch the static transform.
+* Runs inside the gesture transaction, so a whole drag is one undo entry.
+*/
+function applyGestureTransform(engine, elementId, transform, timelineMs) {
+	const element = getElement(engine.project, elementId);
+	if (!element || !("transform" in element)) return;
+	if (GESTURE_PROPERTIES.filter(([property]) => hasKeyframes(element, property)).length === 0) {
+		engine.dispatch({
+			type: "updateElement",
+			elementId,
+			patch: { transform }
+		});
+		return;
+	}
+	const localMs = Math.max(0, Math.round(timelineMs - element.startMs));
+	const staticTransform = { ...element.transform };
+	for (const [property, key] of GESTURE_PROPERTIES) if (hasKeyframes(element, property)) engine.dispatch({
+		type: "setKeyframe",
+		elementId,
+		property,
+		timeMs: localMs,
+		value: transform[key]
+	});
+	else staticTransform[key] = transform[key];
+	engine.dispatch({
+		type: "updateElement",
+		elementId,
+		patch: { transform: staticTransform }
+	});
+}
+/**
+* The preview player: renders the project through the shared compositor on
+* every animation frame, advances the playback clock, keeps the media pool
+* in sync, and hosts the selection overlay (drag / resize / rotate).
+*/
+/**
+* The raster scale for one preview frame: displayed size for `'auto'`
+* (quantized so sub-pixel layout jitter doesn't reallocate the canvas),
+* short-side cap for numeric presets, 1 for `'full'`. Never upscales
+* beyond project resolution.
+*/
+function getRenderScale(project, quality, container) {
+	if (quality === "full") return 1;
+	if (typeof quality === "number") {
+		const shortSide = Math.min(project.width, project.height);
+		return shortSide > 0 ? Math.min(1, quality / shortSide) : 1;
+	}
+	const displayWidth = (container?.clientWidth ?? 0) * (window.devicePixelRatio || 1);
+	if (displayWidth <= 0 || project.width <= 0) return 1;
+	return Math.min(1, Math.ceil(displayWidth / 64) * 64 / project.width);
+}
+function PlayerCanvas({ className, interactive = true, background, quality = "auto", hiddenElementIds, onElementDoubleClick, renderer = "canvas2d" }) {
+	const { engine, pool } = useEditorContext();
+	const containerRef = useRef(null);
+	const renderCanvasRef = useRef(null);
+	const gpuRef = useRef(null);
+	const overlayCanvasRef = useRef(null);
+	const measureCtxRef = useRef(null);
+	const gestureRef = useRef(null);
+	const feedbackRef = useRef({
+		guideVertical: false,
+		guideHorizontal: false,
+		label: null
+	});
+	const sizeHelpers = (project) => ({
+		getAssetSize: (assetId) => {
+			const asset = project.assets[assetId];
+			return asset?.width && asset?.height ? {
+				width: asset.width,
+				height: asset.height
+			} : null;
+		},
+		measureText: (text, style, box, runs) => {
+			if (!measureCtxRef.current) measureCtxRef.current = document.createElement("canvas").getContext("2d");
+			const ctx = measureCtxRef.current;
+			if (!ctx) return {
+				width: 0,
+				height: 0
+			};
+			const layout = layoutTextBlock(measureWith(ctx), text, style, {
+				box,
+				...runs ? { runs } : {}
+			});
+			return {
+				width: layout.width,
+				height: layout.height
+			};
+		}
+	});
+	const obbFor = (project, element) => getElementOBB(project, element, sizeHelpers(project));
+	useEffect(() => {
+		let raf = 0;
+		let lastNow = performance.now();
+		const loop = () => {
+			const now = performance.now();
+			const playback = engine.playback.state;
+			let project = engine.project;
+			if (playback.isPlaying) {
+				const durationMs = getProjectDurationMs(project);
+				const next = playback.currentTimeMs + (now - lastNow) * playback.playbackRate;
+				if (durationMs > 0 && next >= durationMs && playback.playbackRate > 0) {
+					engine.seek(durationMs);
+					engine.pause();
+				} else if (next <= 0 && playback.playbackRate < 0) {
+					engine.seek(0);
+					engine.pause();
+				} else engine.seek(next);
+			}
+			lastNow = now;
+			project = engine.project;
+			const { currentTimeMs, isPlaying, playbackRate, volume, muted } = engine.playback.state;
+			pool.sync(getActiveMediaItems(project, currentTimeMs), {
+				isPlaying,
+				playbackRate,
+				masterVolume: volume,
+				muted
+			});
+			const canvas = renderCanvasRef.current;
+			if (canvas) {
+				const scale = getRenderScale(project, quality, containerRef.current);
+				const width = Math.max(1, Math.round(project.width * scale));
+				const height = Math.max(1, Math.round(project.height * scale));
+				if (canvas.width !== width) canvas.width = width;
+				if (canvas.height !== height) canvas.height = height;
+				const renderOptions = {
+					source: pool,
+					...background ? { backgroundColor: background } : {},
+					...hiddenRef.current && hiddenRef.current.size > 0 ? { skipElementIds: hiddenRef.current } : {}
+				};
+				if (renderer === "webgpu" && isWebGPUSupported()) {
+					const key = `${project.width}x${project.height}`;
+					let gpu = gpuRef.current;
+					if (gpu && gpu.key !== key && gpu.backend) {
+						gpu.backend.dispose();
+						gpu = null;
+					}
+					if (!gpu) {
+						const created = {
+							key,
+							backend: null,
+							pending: true
+						};
+						gpuRef.current = created;
+						gpu = created;
+						WebGPUBackend.create({
+							canvas,
+							width: project.width,
+							height: project.height
+						}).then((backend) => {
+							if (gpuRef.current === created) {
+								created.backend = backend;
+								created.pending = false;
+							} else backend.dispose();
+						}).catch(() => {
+							created.pending = false;
+						});
+					}
+					if (gpu.backend) renderFrameWith(gpu.backend, project, currentTimeMs, renderOptions);
+				} else {
+					const ctx = canvas.getContext("2d");
+					if (ctx) {
+						ctx.setTransform(scale, 0, 0, scale, 0, 0);
+						renderFrame(ctx, project, currentTimeMs, renderOptions);
+					}
+				}
+			}
+			drawOverlay(project, currentTimeMs);
+			raf = requestAnimationFrame(loop);
+		};
+		const drawOverlay = (project, timeMs) => {
+			const overlay = overlayCanvasRef.current;
+			const container = containerRef.current;
+			if (!overlay || !container) return;
+			const dpr = window.devicePixelRatio || 1;
+			const width = Math.max(1, Math.round(container.clientWidth * dpr));
+			const height = Math.max(1, Math.round(container.clientHeight * dpr));
+			if (overlay.width !== width) overlay.width = width;
+			if (overlay.height !== height) overlay.height = height;
+			const ctx = overlay.getContext("2d");
+			if (!ctx) return;
+			ctx.setTransform(1, 0, 0, 1, 0, 0);
+			ctx.clearRect(0, 0, width, height);
+			if (!interactive) return;
+			const selectedId = engine.selection.elementIds[0];
+			if (!selectedId) return;
+			const raw = getElement(project, selectedId);
+			if (!raw || !isElementActiveAt(raw, timeMs)) return;
+			const obb = obbFor(project, resolveAnimatedElement(raw, timeMs));
+			if (!obb) return;
+			const scale = width / project.width;
+			ctx.setTransform(scale, 0, 0, scale, 0, 0);
+			const px = (value) => value / scale;
+			ctx.save();
+			ctx.translate(obb.cx, obb.cy);
+			ctx.rotate(obb.rotation * Math.PI / 180);
+			ctx.strokeStyle = "#3b82f6";
+			ctx.lineWidth = px(1.5);
+			ctx.setLineDash([px(6), px(4)]);
+			ctx.strokeRect(-obb.width / 2, -obb.height / 2, obb.width, obb.height);
+			ctx.restore();
+			ctx.setLineDash([]);
+			for (const handle of getHandles(obb)) {
+				const size = px(handle.id === "rotate" ? 10 : 8);
+				ctx.fillStyle = "#ffffff";
+				ctx.strokeStyle = "#3b82f6";
+				ctx.lineWidth = px(1.5);
+				if (handle.id === "rotate") {
+					ctx.beginPath();
+					ctx.arc(handle.x, handle.y, size / 2, 0, Math.PI * 2);
+					ctx.fill();
+					ctx.stroke();
+				} else {
+					ctx.fillRect(handle.x - size / 2, handle.y - size / 2, size, size);
+					ctx.strokeRect(handle.x - size / 2, handle.y - size / 2, size, size);
+				}
+			}
+			const feedback = feedbackRef.current;
+			if (gestureRef.current) {
+				if (feedback.guideVertical || feedback.guideHorizontal) {
+					ctx.strokeStyle = "#e879f9";
+					ctx.lineWidth = px(1);
+					ctx.setLineDash([px(5), px(4)]);
+					ctx.beginPath();
+					if (feedback.guideVertical) {
+						ctx.moveTo(project.width / 2, 0);
+						ctx.lineTo(project.width / 2, project.height);
+					}
+					if (feedback.guideHorizontal) {
+						ctx.moveTo(0, project.height / 2);
+						ctx.lineTo(project.width, project.height / 2);
+					}
+					ctx.stroke();
+					ctx.setLineDash([]);
+				}
+				if (feedback.label) {
+					const fontPx = px(11);
+					ctx.font = `${fontPx}px ui-monospace, monospace`;
+					const metrics = ctx.measureText(feedback.label);
+					const padding = px(5);
+					const labelY = obb.cy + obb.height / 2 + px(18);
+					ctx.fillStyle = "rgba(0, 0, 0, 0.75)";
+					ctx.beginPath();
+					ctx.roundRect(obb.cx - metrics.width / 2 - padding, labelY - fontPx / 2 - padding, metrics.width + padding * 2, fontPx + padding * 2, px(4));
+					ctx.fill();
+					ctx.fillStyle = "#ffffff";
+					ctx.textAlign = "center";
+					ctx.textBaseline = "middle";
+					ctx.fillText(feedback.label, obb.cx, labelY);
+					ctx.textAlign = "left";
+				}
+			}
+		};
+		raf = requestAnimationFrame(loop);
+		return () => {
+			cancelAnimationFrame(raf);
+			gpuRef.current?.backend?.dispose();
+			gpuRef.current = null;
+		};
+	}, [
+		engine,
+		pool,
+		background,
+		interactive,
+		quality,
+		renderer
+	]);
+	const hiddenRef = useRef(hiddenElementIds);
+	hiddenRef.current = hiddenElementIds;
+	const doubleClickRef = useRef(onElementDoubleClick);
+	doubleClickRef.current = onElementDoubleClick;
+	const toProjectPoint = (event) => {
+		const overlay = overlayCanvasRef.current;
+		const project = engine.project;
+		if (!overlay) return null;
+		const rect = overlay.getBoundingClientRect();
+		if (rect.width === 0 || rect.height === 0) return null;
+		return {
+			x: (event.clientX - rect.left) / rect.width * project.width,
+			y: (event.clientY - rect.top) / rect.height * project.height
+		};
+	};
+	const screenToProject = () => {
+		const overlay = overlayCanvasRef.current;
+		if (!overlay) return 1;
+		const rect = overlay.getBoundingClientRect();
+		return rect.width === 0 ? 1 : engine.project.width / rect.width;
+	};
+	const handlePointerDown = (event) => {
+		if (!interactive) return;
+		const point = toProjectPoint(event);
+		if (!point) return;
+		const project = engine.project;
+		const timeMs = engine.playback.state.currentTimeMs;
+		const handleHitSize = 10 * screenToProject();
+		const selectedId = engine.selection.elementIds[0];
+		if (selectedId) {
+			const raw = getElement(project, selectedId);
+			if (raw && isElementActiveAt(raw, timeMs) && "transform" in raw) {
+				const element = resolveAnimatedElement(raw, timeMs);
+				const obb = obbFor(project, element);
+				if (obb) {
+					const handle = hitTestHandles(obb, point.x, point.y, handleHitSize);
+					if (handle) {
+						const baseBox = handle !== "rotate" && element.type === "text" && element.box ? {
+							...element.box,
+							height: element.box.height ?? obb.height / element.transform.scaleY,
+							hadHeight: element.box.height !== void 0
+						} : null;
+						gestureRef.current = {
+							kind: handle === "rotate" ? "rotate" : baseBox ? "box-resize" : "resize",
+							elementId: element.id,
+							baseTransform: element.transform,
+							baseOBB: obb,
+							baseBox,
+							handle: handle === "rotate" ? null : handle,
+							start: point
+						};
+						engine.beginTransaction();
+						event.currentTarget.setPointerCapture(event.pointerId);
+						return;
+					}
+				}
+			}
+		}
+		for (let trackIndex = project.tracks.length - 1; trackIndex >= 0; trackIndex--) {
+			const track = project.tracks[trackIndex];
+			if (track.hidden || track.locked) continue;
+			for (let i = track.elements.length - 1; i >= 0; i--) {
+				const raw = track.elements[i];
+				if (!isElementActiveAt(raw, timeMs)) continue;
+				if (!("transform" in raw)) continue;
+				const element = resolveAnimatedElement(raw, timeMs);
+				const obb = obbFor(project, element);
+				if (!obb || !hitTestOBB(obb, point.x, point.y)) continue;
+				engine.select([element.id]);
+				gestureRef.current = {
+					kind: "move",
+					elementId: element.id,
+					baseTransform: element.transform,
+					baseOBB: obb,
+					baseBox: null,
+					handle: null,
+					start: point
+				};
+				engine.beginTransaction();
+				event.currentTarget.setPointerCapture(event.pointerId);
+				return;
+			}
+		}
+		engine.clearSelection();
+	};
+	const handleDoubleClick = (event) => {
+		if (!interactive || !doubleClickRef.current) return;
+		const point = toProjectPoint(event);
+		if (!point) return;
+		const project = engine.project;
+		const timeMs = engine.playback.state.currentTimeMs;
+		for (let trackIndex = project.tracks.length - 1; trackIndex >= 0; trackIndex--) {
+			const track = project.tracks[trackIndex];
+			if (track.hidden || track.locked) continue;
+			for (let i = track.elements.length - 1; i >= 0; i--) {
+				const raw = track.elements[i];
+				if (!isElementActiveAt(raw, timeMs)) continue;
+				if (!("transform" in raw)) continue;
+				const element = resolveAnimatedElement(raw, timeMs);
+				const obb = obbFor(project, element);
+				if (!obb || !hitTestOBB(obb, point.x, point.y)) continue;
+				doubleClickRef.current(element.id);
+				return;
+			}
+		}
+	};
+	const handlePointerMove = (event) => {
+		const gesture = gestureRef.current;
+		if (!gesture) return;
+		const point = toProjectPoint(event);
+		if (!point) return;
+		let transform;
+		const feedback = feedbackRef.current;
+		if (gesture.kind === "move") {
+			transform = applyMove(gesture.baseTransform, gesture.start, point);
+			const threshold = CENTER_SNAP_PX * screenToProject();
+			feedback.guideVertical = false;
+			feedback.guideHorizontal = false;
+			if (!event.altKey) {
+				if (Math.abs(transform.x) < threshold) {
+					transform = {
+						...transform,
+						x: 0
+					};
+					feedback.guideVertical = true;
+				}
+				if (Math.abs(transform.y) < threshold) {
+					transform = {
+						...transform,
+						y: 0
+					};
+					feedback.guideHorizontal = true;
+				}
+			}
+			feedback.label = null;
+		} else if (gesture.kind === "rotate") {
+			transform = applyRotate(gesture.baseTransform, gesture.baseOBB, gesture.start, point);
+			feedback.label = `${transform.rotation.toFixed(1)}°`;
+			feedback.guideVertical = false;
+			feedback.guideHorizontal = false;
+		} else if (gesture.kind === "resize") {
+			transform = applyResize(gesture.baseTransform, gesture.baseOBB, gesture.handle ?? "se", gesture.start, point);
+			const width = gesture.baseOBB.width / gesture.baseTransform.scaleX * transform.scaleX;
+			const height = gesture.baseOBB.height / gesture.baseTransform.scaleY * transform.scaleY;
+			feedback.label = `${Math.round(width)}×${Math.round(height)}`;
+			feedback.guideVertical = false;
+			feedback.guideHorizontal = false;
+		} else {
+			const baseBox = gesture.baseBox;
+			if (!baseBox || !gesture.handle) return;
+			const result = applyBoxResize(gesture.baseTransform, gesture.baseOBB, gesture.handle, point, 12 * screenToProject());
+			transform = result.transform;
+			const nextWidth = Math.max(1, Math.round(result.displayWidth / gesture.baseTransform.scaleX));
+			const nextHeight = Math.max(1, Math.round(result.displayHeight / gesture.baseTransform.scaleY));
+			const resizesHeight = gesture.handle.includes("n") || gesture.handle.includes("s");
+			const box = {
+				width: nextWidth,
+				overflow: baseBox.overflow,
+				...baseBox.hadHeight || resizesHeight ? { height: nextHeight } : {}
+			};
+			try {
+				applyGestureTransform(engine, gesture.elementId, transform, engine.playback.state.currentTimeMs);
+				engine.dispatch({
+					type: "updateElement",
+					elementId: gesture.elementId,
+					patch: { box }
+				});
+			} catch {
+				gestureRef.current = null;
+				engine.endTransaction();
+			}
+			feedback.label = `${Math.round(result.displayWidth)}×${Math.round(result.displayHeight)}`;
+			feedback.guideVertical = false;
+			feedback.guideHorizontal = false;
+			return;
+		}
+		try {
+			applyGestureTransform(engine, gesture.elementId, transform, engine.playback.state.currentTimeMs);
+		} catch {
+			gestureRef.current = null;
+			engine.endTransaction();
+		}
+	};
+	const endGesture = (event) => {
+		if (!gestureRef.current) return;
+		gestureRef.current = null;
+		feedbackRef.current = {
+			guideVertical: false,
+			guideHorizontal: false,
+			label: null
+		};
+		engine.endTransaction();
+		event.currentTarget.releasePointerCapture(event.pointerId);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		ref: containerRef,
+		className,
+		style: {
+			position: "relative",
+			aspectRatio: "var(--mcut-aspect, 16 / 9)",
+			width: "100%"
+		},
+		"data-mcut-player": "",
+		children: [/* @__PURE__ */ jsx("canvas", {
+			ref: renderCanvasRef,
+			style: {
+				position: "absolute",
+				inset: 0,
+				width: "100%",
+				height: "100%"
+			}
+		}, renderer), /* @__PURE__ */ jsx("canvas", {
+			ref: overlayCanvasRef,
+			style: {
+				position: "absolute",
+				inset: 0,
+				width: "100%",
+				height: "100%",
+				touchAction: "none",
+				cursor: interactive ? "default" : void 0
+			},
+			onPointerDown: handlePointerDown,
+			onPointerMove: handlePointerMove,
+			onPointerUp: endGesture,
+			onPointerCancel: endGesture,
+			onDoubleClick: handleDoubleClick
+		})]
+	});
+}
+//#endregion
+export { EditorProvider, PlayerCanvas, applyBoxResize, applyMove, applyResize, applyRotate, useEditor, useEditorContext, useEditorState, usePlayback, useProject, useSelectedElement, useSelection };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@mcut/react",
+  "version": "0.1.0-alpha.0",
+  "description": "React bindings for mcut: EditorProvider, hooks, PlayerCanvas with selection overlay, playback clock, audio preview",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattppal/mcut.git",
+    "directory": "packages/react"
+  },
+  "dependencies": {
+    "@mcut/compositor": "0.1.0-alpha.0",
+    "@mcut/media": "0.1.0-alpha.0",
+    "@mcut/timeline": "0.1.0-alpha.0",
+    "@tanstack/react-store": "0.11.0"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3"
+  },
+  "author": "Matt Palmer",
+  "homepage": "https://github.com/mattppal/mcut/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/mattppal/mcut/issues"
+  },
+  "keywords": [
+    "mcut",
+    "video",
+    "video-editing",
+    "timeline",
+    "typescript",
+    "react",
+    "hooks",
+    "player"
+  ]
+}