π₯ Make videos programmatically with React
`@remotion/canvas`: Define and document public authoring API
Jonny Burger4c8ce226636f
diff --git a/bun.lock b/bun.lockindex ca34085a07..5b61c89348 100644--- a/bun.lock+++ b/bun.lock@@ -582,6 +582,7 @@"@remotion/browser-bundler": "workspace:*","@remotion/browser-studio": "workspace:*","@remotion/bundler": "workspace:*",+ "@remotion/canvas": "workspace:*","@remotion/captions": "workspace:*","@remotion/cli": "workspace:*","@remotion/cloudrun": "workspace:*",diff --git a/packages/canvas/README.md b/packages/canvas/README.mdindex ee01ad0cba..c093a9a696 100644--- a/packages/canvas/README.md+++ b/packages/canvas/README.md@@ -1,76 +1,7 @@# @remotion/canvas-Headless primitives for Remotion authoring interfaces+Experimental primitives for building a Remotion authoring interface around [`@remotion/player`](https://www.remotion.dev/docs/player/player).-## Usage+See the [Canvas documentation](https://www.remotion.dev/docs/canvas) for installation, a complete example, and the supported API.-`Canvas` accepts the Player props plus a controller. Outlines are opt-in:--```tsx-const controller = useCanvasController();--<Canvas- controller={controller}- showOutlines- component={Video}- compositionWidth={1920}- compositionHeight={1080}- durationInFrames={150}- fps={30}-/>;-```--In outline mode, the composition handles hover and click selection. Shift-click-selects a range, Cmd/Ctrl-click toggles an item, and clicking empty space or-pressing Escape on the canvas clears selection. Player controls remain usable.-Set `showOutlines={false}` to interact with the composition's own controls.--Subscribe to `controller.timeline` for registered layers and use-`useCanvasSelection(controller.selection)` for selection. Use-`getCanvasSequenceNodePathInfo(track)` to construct each layer's selection item-and `useCanvasSequenceHover(controller.hover, nodePathInfo, 'timeline')` for-bidirectional hover highlighting. The hook returns `hovered`, `onPointerEnter`,-and `onPointerLeave`; each layer subscribes only to its own hover state.--If the host resolves source identities, pass `resolveSequenceNodePathInfo` to-`Canvas` and use the same resolver in the layer list. Return `null` for layers-that should not be selectable. The default uses an existing source identity or-falls back to the mounted sequence ID; that fallback is not a persistent source-reference across remounts. Outlines require a registered DOM ref, so a-`Sequence` with `layout="none"` has no outline of its own.--For custom authoring UIs, Studio and Canvas consume the same outline APIs:--- `getCanvasSelectableOutlines()` discovers registered outline targets;- `getCanvasVisibleOutlineTargets()` filters them by frame.-- `getCanvasOutlineActivity()` gates active measurement, and- `getCanvasActiveOutlineTargets()` keeps selected or hovered source groups- active when the pointer leaves the canvas.-- `getCanvasOutlineLayoutTargets()` distinguishes direct sequence selection- from selected properties, highlights matching source instances, and resolves- clicks to the first visible instance of a source node.-- `useCanvasOutlines()` measures targets, clears stale canvas hover, and returns- `outlinesForRendering`, `outlinesByKey`, `targetsByKey`, and- `hoveredNodePathKey`. Set `freezeOrder` during a captured drag to keep SVG- nodes in place. Supply `crop` alongside the layout target fields.-- `CanvasOutlinePolygon` renders the SVG polygon with shared geometry and hover- behavior. Render it inside your overlay's `<svg>`, pass visibility, selection,- colors, and `onHoverChange`, and compose editing handlers through normal SVG- props. It forwards its ref for pointer capture and hit testing.-- `handleCanvasOutlinePointerDown()` consumes a primary pointer event and- returns a selection decision, preserving an existing multiselection on plain- clicks. Dragging hosts honor `deferSelection` until release; selection-only- hosts apply `shouldUpdateSelection` immediately. Studio adds its drag and- source-editing behavior around this decision.--Lower-level `createCanvasHoverController()`, `measureCanvasOutlineTargets()`,-`useCanvasOutlineMeasurements()`, and `orderCanvasOutlinesForRendering()` remain-available independently. Measurements include transformed HTML/SVG bounds and cropping, in-unscaled overlay pixels. The overlay must share the elements' document and-must not have a CSS transform or SVG viewBox scaling. The measurement hook-observes element sizes; invoke its `updateOutlinesRef` after position, transform,-frame, or viewport changes. Keep frame subscriptions in the active overlay and-omit inactive targets to avoid unnecessary layout reads. `useCanvasOutlines()`-also accepts this ref and does not subscribe to playback itself.--Source writes and transform editing handles remain the host's responsibility.+The `@remotion/canvas/internal` entry point is used by Remotion Studio and may change without notice.diff --git a/packages/canvas/bundle.ts b/packages/canvas/bundle.tsindex aecd71a704..7de0878b40 100644--- a/packages/canvas/bundle.ts+++ b/packages/canvas/bundle.ts@@ -9,12 +9,12 @@ const external = ['@remotion/player', 'react', 'react-dom', 'remotion'];console.time('Generated.');const esmOutput = await build({- entrypoints: ['src/index.ts'],+ entrypoints: ['src/index.ts', 'src/internal.ts'],naming: '[name].mjs',external,});const cjsOutput = await build({- entrypoints: ['src/index.ts'],+ entrypoints: ['src/index.ts', 'src/internal.ts'],naming: '[name].cjs',format: 'cjs',external,diff --git a/packages/canvas/package.json b/packages/canvas/package.jsonindex 478f8e1c7b..0b1e3c3dcf 100644--- a/packages/canvas/package.json+++ b/packages/canvas/package.json@@ -33,6 +33,12 @@},"exports": {"./package.json": "./package.json",+ "./internal": {+ "types": "./dist/internal.d.ts",+ "require": "./dist/internal.cjs",+ "module": "./dist/esm/internal.mjs",+ "import": "./dist/esm/internal.mjs"+ },".": {"types": "./dist/index.d.ts","require": "./dist/index.cjs",diff --git a/packages/canvas/src/index.ts b/packages/canvas/src/index.tsindex c4f2c1df58..5a83a3b51e 100644--- a/packages/canvas/src/index.ts+++ b/packages/canvas/src/index.ts@@ -1,4 +1,3 @@-export {calculateTimeline} from './calculate-timeline';export {Canvas} from './canvas';export type {CanvasProps} from './canvas';export {createCanvasController, useCanvasController} from './canvas-controller';@@ -7,77 +6,14 @@ export {createCanvasHoverController,useCanvasHover,useCanvasSequenceHover,- useIsCanvasSequenceHovered,} from './hover';export type {CanvasHover, CanvasHoverController} from './hover';-export type {- CanvasOutline,- CanvasOutlinePoint,- CanvasOutlineUv,- CanvasOutlineCrop,- CanvasOutlineTarget,-} from './outline-geometry';-export {getCanvasOutlinePoint, getCanvasOutlineUv} from './outline-geometry';-export {- measureCanvasOutlineTargets,- cropCanvasOutlinePoints,- canvasOutlinesAreEqual,- getTransformedSvgViewportPoints,-} from './outline-measurement';-export {orderCanvasOutlinesForRendering} from './outline-order';-export type {- CanvasOutlineOrderTarget,- CanvasOutlineSequenceParent,-} from './outline-order';-export {useCanvasOutlineMeasurements} from './use-canvas-outline-measurements';-export {useCanvasOutlines} from './use-canvas-outlines';-export type {CanvasOutlineRenderTarget} from './use-canvas-outlines';-export {CanvasOutlinePolygon} from './canvas-outline-polygon';-export type {CanvasOutlinePolygonProps} from './canvas-outline-polygon';-export {- getCanvasOutlineSelectionInteraction,- handleCanvasOutlinePointerDown,-} from './outline-interaction';-export type {CanvasOutlinePointerDownDecision} from './outline-interaction';-export {- getCanvasActiveOutlineTargets,- getCanvasOutlineActivity,- getCanvasOutlineLayoutTargets,- getCanvasSelectableOutlines,- getCanvasSelectedSequenceKeys,- getCanvasSequenceKeysContainingSelection,- getCanvasVisibleOutlineTargets,-} from './outline-targets';-export type {- CanvasSelectableOutline,- CanvasOutlineLayoutTarget,-} from './outline-targets';export {getCanvasSequenceNodePathInfo} from './sequence-node-path';export type {CanvasSequenceNodePathResolver} from './sequence-node-path';-export {getConnectedCompositions} from './get-connected-compositions';-export {- getParentSequencePlaybackRate,- getCascadedStart,- getCascadedStartWithTrim,- getTimelineVisibleDuration,- getTimelineVisibleStart,-} from './get-sequence-visible-range';-export {getTimelineNestedLevel} from './get-timeline-nestedness';-export {getTimelineSequenceSortKey} from './get-timeline-sequence-sort-key';-export type {- SequenceNodePathInfo,- TimelineLoopDisplay,- TimelineTrackData,- TimelineTrackWithOriginalTimings,-} from './get-timeline-sequence-sort-key';export {createCanvasSelectionController,- EMPTY_CANVAS_SELECTION,- getCanvasSelectionAfterInteraction,getCanvasSelectionItemKey,- getCanvasSequenceSelectionKey,useCanvasSelection,- useCanvasSelectionController,} from './selection';export type {CanvasSelectionController,@@ -85,6 +21,7 @@ export type {CanvasSelectionInteraction,CanvasSelectionSnapshot,} from './selection';-export {sortItemsByCommitOrder} from './sort-by-commit-order';-export {timelineSequenceNodePathToKey} from './timeline-sequence-node-path-to-key';-export {useCanvasRuntimeValueSnapshots} from './use-runtime-value-snapshots';+export type {+ SequenceNodePathInfo,+ TimelineTrackData,+} from './get-timeline-sequence-sort-key';diff --git a/packages/canvas/src/internal.ts b/packages/canvas/src/internal.tsnew file mode 100644index 0000000000..1a855bcf40--- /dev/null+++ b/packages/canvas/src/internal.ts@@ -0,0 +1,91 @@+// Shared with Remotion Studio. This entry point is not part of the supported @remotion/canvas API.+export {calculateTimeline} from './calculate-timeline';+export {Canvas} from './canvas';+export type {CanvasProps} from './canvas';+export {createCanvasController, useCanvasController} from './canvas-controller';+export type {CanvasController} from './canvas-controller';+export {+ createCanvasHoverController,+ useCanvasHover,+ useCanvasSequenceHover,+ useIsCanvasSequenceHovered,+} from './hover';+export type {CanvasHover, CanvasHoverController} from './hover';+export type {+ CanvasOutline,+ CanvasOutlinePoint,+ CanvasOutlineUv,+ CanvasOutlineCrop,+ CanvasOutlineTarget,+} from './outline-geometry';+export {getCanvasOutlinePoint, getCanvasOutlineUv} from './outline-geometry';+export {+ measureCanvasOutlineTargets,+ cropCanvasOutlinePoints,+ canvasOutlinesAreEqual,+ getTransformedSvgViewportPoints,+} from './outline-measurement';+export {orderCanvasOutlinesForRendering} from './outline-order';+export type {+ CanvasOutlineOrderTarget,+ CanvasOutlineSequenceParent,+} from './outline-order';+export {useCanvasOutlineMeasurements} from './use-canvas-outline-measurements';+export {useCanvasOutlines} from './use-canvas-outlines';+export type {CanvasOutlineRenderTarget} from './use-canvas-outlines';+export {CanvasOutlinePolygon} from './canvas-outline-polygon';+export type {CanvasOutlinePolygonProps} from './canvas-outline-polygon';+export {+ getCanvasOutlineSelectionInteraction,+ handleCanvasOutlinePointerDown,+} from './outline-interaction';+export type {CanvasOutlinePointerDownDecision} from './outline-interaction';+export {+ getCanvasActiveOutlineTargets,+ getCanvasOutlineActivity,+ getCanvasOutlineLayoutTargets,+ getCanvasSelectableOutlines,+ getCanvasSelectedSequenceKeys,+ getCanvasSequenceKeysContainingSelection,+ getCanvasVisibleOutlineTargets,+} from './outline-targets';+export type {+ CanvasSelectableOutline,+ CanvasOutlineLayoutTarget,+} from './outline-targets';+export {getCanvasSequenceNodePathInfo} from './sequence-node-path';+export type {CanvasSequenceNodePathResolver} from './sequence-node-path';+export {getConnectedCompositions} from './get-connected-compositions';+export {+ getParentSequencePlaybackRate,+ getCascadedStart,+ getCascadedStartWithTrim,+ getTimelineVisibleDuration,+ getTimelineVisibleStart,+} from './get-sequence-visible-range';+export {getTimelineNestedLevel} from './get-timeline-nestedness';+export {getTimelineSequenceSortKey} from './get-timeline-sequence-sort-key';+export type {+ SequenceNodePathInfo,+ TimelineLoopDisplay,+ TimelineTrackData,+ TimelineTrackWithOriginalTimings,+} from './get-timeline-sequence-sort-key';+export {+ createCanvasSelectionController,+ EMPTY_CANVAS_SELECTION,+ getCanvasSelectionAfterInteraction,+ getCanvasSelectionItemKey,+ getCanvasSequenceSelectionKey,+ useCanvasSelection,+ useCanvasSelectionController,+} from './selection';+export type {+ CanvasSelectionController,+ CanvasSelectionItem,+ CanvasSelectionInteraction,+ CanvasSelectionSnapshot,+} from './selection';+export {sortItemsByCommitOrder} from './sort-by-commit-order';+export {timelineSequenceNodePathToKey} from './timeline-sequence-node-path-to-key';+export {useCanvasRuntimeValueSnapshots} from './use-runtime-value-snapshots';diff --git a/packages/docs/docs/canvas/canvas.mdx b/packages/docs/docs/canvas/canvas.mdxnew file mode 100644index 0000000000..7c13f807ed--- /dev/null+++ b/packages/docs/docs/canvas/canvas.mdx@@ -0,0 +1,66 @@+---+image: /generated/articles-docs-canvas-canvas.png+title: '<Canvas>'+slug: /canvas/canvas+crumb: '@remotion/canvas'+---++# <Canvas><AvailableFrom v="4.0.527" />++Renders a Remotion composition using [`<Player>`](/docs/player/player), registers its timeline tracks, and optionally overlays selection outlines. Import it from `@remotion/canvas`.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```tsx title="Preview.tsx"+import {Canvas, useCanvasController} from '@remotion/canvas';+import {Video} from './Video';++export const Preview = () => {+ const controller = useCanvasController();+ return (+ <Canvas+ controller={controller}+ showOutlines+ component={Video}+ compositionWidth={1920}+ compositionHeight={1080}+ durationInFrames={150}+ fps={30}+ />+ );+};+```++## Props++`CanvasProps` includes the [`<Player>` props](/docs/player/player) and the props below. `<Canvas>` forwards its ref to the Player.++### controller++A [`CanvasController`](/docs/canvas/create-canvas-controller) shared with your timeline and selection UI. Keep it stable while the Canvas is mounted.++### showOutlines?++Whether to draw hover and selection outlines over the composition. Default: `false`. When enabled, pointer events select outlines instead of reaching interactive controls inside the composition. Set it to `false` for an interaction mode that lets users operate those controls.++Clicking empty canvas space or pressing Escape while the overlay is focused clears selection. Shift-click selects a range; Command-click on macOS or Ctrl-click elsewhere toggles an item.++### resolveSequenceNodePathInfo?++A `CanvasSequenceNodePathResolver` called with a [`TimelineTrackData`](/docs/canvas/create-canvas-controller#timeline) and its index. It returns a `SequenceNodePathInfo` identity or `null` to make the track unselectable. The default is [`getCanvasSequenceNodePathInfo()`](/docs/canvas/get-canvas-sequence-node-path-info).++Use the same resolver when constructing selection items for the layer list. Keep its function identity stable where possible, for example with `useCallback()`.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [Canvas overview and layer list example](/docs/canvas)+- [`useCanvasController()`](/docs/canvas/use-canvas-controller)+- [`useCanvasSelection()`](/docs/canvas/use-canvas-selection)diff --git a/packages/docs/docs/canvas/create-canvas-controller.mdx b/packages/docs/docs/canvas/create-canvas-controller.mdxnew file mode 100644index 0000000000..7dc3a2e15a--- /dev/null+++ b/packages/docs/docs/canvas/create-canvas-controller.mdx@@ -0,0 +1,65 @@+---+image: /generated/articles-docs-canvas-create-canvas-controller.png+title: createCanvasController()+crumb: '@remotion/canvas'+---++# createCanvasController()<AvailableFrom v="4.0.527" />++Creates a `CanvasController` to share between [`<Canvas>`](/docs/canvas/canvas) and your editor UI. Import it from `@remotion/canvas`. In React components, [`useCanvasController()`](/docs/canvas/use-canvas-controller) keeps one controller across renders.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```ts title="controller.ts"+import {createCanvasController} from '@remotion/canvas';++export const controller = createCanvasController();+```++The function takes no arguments.++## Return value++### timeline++An external store of `readonly TimelineTrackData[]`. Subscribe with `timeline.subscribe(listener)` and read with `timeline.getSnapshot()`. In React, pass both to `useSyncExternalStore()` as shown in the [overview](/docs/canvas#basic-example). Tracks are populated while the composition is mounted and cleared when `<Canvas>` unmounts.++Each track includes `sequence` registration data, `depth`, `nodePathInfo`, and timing fields such as `cascadedStart`, `localStart`, `keyframeDisplayOffset`, `keyframePlaybackRate`, and `sequenceFrameOffset`. The sequence's `from` and `duration` are its visible timeline range. `nodePathInfo` may be `null` when no source identity was registered.++### selection++A `CanvasSelectionController` with `getSnapshot()` and `subscribe(listener)` for reading selection. Use [`useCanvasSelection()`](/docs/canvas/use-canvas-selection) in React.++#### select()++`select(item, interaction, allSelectableItems)` applies one selection interaction. `interaction` has `shiftKey` for range selection and `toggleKey` for Command/Ctrl toggling. `allSelectableItems` is the ordered list used to calculate ranges.++#### setSelectedItems()++`setSelectedItems(items)` replaces the selected items and uses the last item as the range anchor.++#### setSnapshot()++`setSnapshot({selectedItems, anchor})` replaces the complete selection state.++#### clear()++`clear()` removes every selection item.++### hover++A `CanvasHoverController` with `getSnapshot()`, `subscribe(listener)`, `setHoveredSequence(valueOrUpdater)`, and `clear(source)`. Use [`useCanvasSequenceHover()`](/docs/canvas/use-canvas-sequence-hover) for a layer row or [`useCanvasHover()`](/docs/canvas/use-canvas-hover) to read the current hover. `clear('canvas')` or `clear('timeline')` only clears hover from that source; `clear(null)` clears either source.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`<Canvas>`](/docs/canvas/canvas)+- [`useCanvasController()`](/docs/canvas/use-canvas-controller)+- [`useCanvasSelection()`](/docs/canvas/use-canvas-selection)diff --git a/packages/docs/docs/canvas/create-canvas-hover-controller.mdx b/packages/docs/docs/canvas/create-canvas-hover-controller.mdxnew file mode 100644index 0000000000..ec37954780--- /dev/null+++ b/packages/docs/docs/canvas/create-canvas-hover-controller.mdx@@ -0,0 +1,51 @@+---+image: /generated/articles-docs-canvas-create-canvas-hover-controller.png+title: createCanvasHoverController()+crumb: '@remotion/canvas'+---++# createCanvasHoverController()<AvailableFrom v="4.0.527" />++Creates a standalone `CanvasHoverController`. Import it from `@remotion/canvas`. [`createCanvasController()`](/docs/canvas/create-canvas-controller) already creates one at `controller.hover`; use this function when hover has a separate lifetime.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```ts title="hover.ts"+import {createCanvasHoverController} from '@remotion/canvas';++export const hover = createCanvasHoverController();+hover.clear(null);+```++The function takes no arguments. The initial snapshot is `null`. Read and subscribe with [`useCanvasHover()`](/docs/canvas/use-canvas-hover), or use `getSnapshot()` and `subscribe(listener)` outside React.++## Methods++### setHoveredSequence()++Accepts a `CanvasHover` value, `null`, or an updater function. A `CanvasHover` has `key` for the instance, `nodePathKey` for the source node, and `source` (`'canvas'` or `'timeline'`). Identical values do not emit an update.++### clear()++`clear('canvas')` or `clear('timeline')` clears hover only when it came from that source. `clear(null)` clears hover regardless of source.++### getSnapshot()++Returns the current `CanvasHover` or `null`.++### subscribe()++`subscribe(listener)` calls `listener` after a hover update and returns an unsubscribe function.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`useCanvasHover()`](/docs/canvas/use-canvas-hover)+- [`useCanvasSequenceHover()`](/docs/canvas/use-canvas-sequence-hover)diff --git a/packages/docs/docs/canvas/create-canvas-selection-controller.mdx b/packages/docs/docs/canvas/create-canvas-selection-controller.mdxnew file mode 100644index 0000000000..4a00c51d78--- /dev/null+++ b/packages/docs/docs/canvas/create-canvas-selection-controller.mdx@@ -0,0 +1,59 @@+---+image: /generated/articles-docs-canvas-create-canvas-selection-controller.png+title: createCanvasSelectionController()+crumb: '@remotion/canvas'+---++# createCanvasSelectionController()<AvailableFrom v="4.0.527" />++Creates a standalone `CanvasSelectionController`. Import it from `@remotion/canvas`. [`createCanvasController()`](/docs/canvas/create-canvas-controller) already creates one at `controller.selection`; use this function when selection has a separate lifetime.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```ts title="selection.ts"+import {createCanvasSelectionController} from '@remotion/canvas';++export const selection = createCanvasSelectionController();+selection.setSelectedItems([]);+```++The function takes no arguments. The initial snapshot is `{selectedItems: [], anchor: null}`. Read and subscribe to it with [`useCanvasSelection()`](/docs/canvas/use-canvas-selection), or use `getSnapshot()` and `subscribe(listener)` outside React.++## Methods++### select()++`select(item, interaction, allSelectableItems)` applies a click. The interaction has `shiftKey` and `toggleKey` booleans; the ordered `allSelectableItems` array defines Shift selection ranges. A plain click replaces selection, Shift selects a range of the same item type, and toggle adds or removes compatible items.++### setSelectedItems()++`setSelectedItems(items)` replaces the selection and sets the anchor to the last item, or `null` for an empty array.++### setSnapshot()++`setSnapshot({selectedItems, anchor})` replaces the entire selection state.++### clear()++`clear()` resets the state to an empty selection.++### getSnapshot()++Returns the current `CanvasSelectionSnapshot`.++### subscribe()++`subscribe(listener)` calls `listener` after a selection update and returns an unsubscribe function.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`useCanvasSelection()`](/docs/canvas/use-canvas-selection)+- [`createCanvasController()`](/docs/canvas/create-canvas-controller)diff --git a/packages/docs/docs/canvas/get-canvas-selection-item-key.mdx b/packages/docs/docs/canvas/get-canvas-selection-item-key.mdxnew file mode 100644index 0000000000..23419a9fd8--- /dev/null+++ b/packages/docs/docs/canvas/get-canvas-selection-item-key.mdx@@ -0,0 +1,49 @@+---+image: /generated/articles-docs-canvas-get-canvas-selection-item-key.png+title: getCanvasSelectionItemKey()+crumb: '@remotion/canvas'+---++# getCanvasSelectionItemKey()<AvailableFrom v="4.0.527" />++Returns an identity string for a `CanvasSelectionItem`. Import it from `@remotion/canvas`. Use it to compare selection items from different snapshots or construct React list keys.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```ts title="is-selected.ts"+import {+ getCanvasSelectionItemKey,+ type CanvasSelectionItem,+ type CanvasSelectionSnapshot,+} from '@remotion/canvas';++export const isSelected = (+ item: CanvasSelectionItem,+ selection: CanvasSelectionSnapshot,+) => selection.selectedItems.some(+ (selected) => getCanvasSelectionItemKey(selected) === getCanvasSelectionItemKey(item),+);+```++## Parameter++### item++A `CanvasSelectionItem`, such as `{type: 'sequence', nodePathInfo}`. Other item types can represent a property, effect, keyframe, easing segment, or guide.++## Return value++A string that is equal for items with the same selection identity. Treat its format as opaque; it may change while the package is experimental. If an item's `nodePathInfo` uses the fallback mounted sequence ID from [`getCanvasSequenceNodePathInfo()`](/docs/canvas/get-canvas-sequence-node-path-info), its key can change after a remount.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`useCanvasSelection()`](/docs/canvas/use-canvas-selection)+- [`getCanvasSequenceNodePathInfo()`](/docs/canvas/get-canvas-sequence-node-path-info)diff --git a/packages/docs/docs/canvas/get-canvas-sequence-node-path-info.mdx b/packages/docs/docs/canvas/get-canvas-sequence-node-path-info.mdxnew file mode 100644index 0000000000..1d83b5a55d--- /dev/null+++ b/packages/docs/docs/canvas/get-canvas-sequence-node-path-info.mdx@@ -0,0 +1,71 @@+---+image: /generated/articles-docs-canvas-get-canvas-sequence-node-path-info.png+title: getCanvasSequenceNodePathInfo()+crumb: '@remotion/canvas'+---++# getCanvasSequenceNodePathInfo()<AvailableFrom v="4.0.527" />++Returns the selection identity for a timeline track. Import it from `@remotion/canvas`. This is the default resolver used by [`<Canvas>`](/docs/canvas/canvas).++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```ts title="selection-item.ts"+import {+ getCanvasSequenceNodePathInfo,+ type CanvasSelectionItem,+ type TimelineTrackData,+} from '@remotion/canvas';++export const getItem = (track: TimelineTrackData): CanvasSelectionItem => ({+ type: 'sequence',+ nodePathInfo: getCanvasSequenceNodePathInfo(track),+});+```++## Parameter++### track++A `TimelineTrackData` from [`controller.timeline`](/docs/canvas/create-canvas-controller#timeline).++## Return value++A `SequenceNodePathInfo`. When the track has a registered `nodePathInfo`, that value is returned. Otherwise the function constructs an identity from the mounted sequence ID. The fallback identity is not a persistent source reference across remounts.++### sequenceSubscriptionKey++Identifies the source node and sequence instance. It contains `absolutePath`, `nodePath`, `sequenceKeys`, `effectKeys`, and `videoConfigValues`. The fallback uses the mounted sequence ID in `nodePath`.++### auxiliaryKeys++Additional keys used to distinguish nested selectable parts. The fallback returns an empty array.++### index++The zero-based index of this instance among sequences with the same source node path. The fallback returns `0`.++### numberOfSequencesWithThisNodePath++The number of registered instances with this source node path. The fallback returns `1`.++### supportsEffects++Whether the sequence's registered controls support effects.++## Custom source identity++For an editor that knows which source file and JSX node produced each track, pass a `CanvasSequenceNodePathResolver` to `<Canvas>` and use it to construct layer selection items. The resolver receives `(track, index)` and may return `null` to exclude a track from selection. A stable source identity keeps selection attached to source code after a composition remount.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`<Canvas>`](/docs/canvas/canvas)+- [`getCanvasSelectionItemKey()`](/docs/canvas/get-canvas-selection-item-key)diff --git a/packages/docs/docs/canvas/index.mdx b/packages/docs/docs/canvas/index.mdxnew file mode 100644index 0000000000..2788865536--- /dev/null+++ b/packages/docs/docs/canvas/index.mdx@@ -0,0 +1,135 @@+---+image: /generated/articles-docs-canvas-index.png+sidebar_label: Overview+title: '@remotion/canvas'+crumb: '@remotion/canvas'+---++# @remotion/canvas<AvailableFrom v="4.0.527" />++Build a composition preview and layer list for a Remotion authoring interface. The package combines [`<Player>`](/docs/player/player) playback with registered sequence data, selection, and synchronized hover.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++## Installation++<Installation pkg="@remotion/canvas" />++Install [`@remotion/player`](/docs/player/installation) as well. Keep the Remotion packages on the same version.++## Basic example++Pass the same controller to [`<Canvas>`](/docs/canvas/canvas) and your layer list. `showOutlines` enables hover and selection on the composition.++```tsx title="Editor.tsx"+import {+ Canvas,+ getCanvasSelectionItemKey,+ getCanvasSequenceNodePathInfo,+ useCanvasController,+ useCanvasSelection,+ useCanvasSequenceHover,+ type CanvasSelectionItem,+ type TimelineTrackData,+} from '@remotion/canvas';+import {useSyncExternalStore} from 'react';+import {Video} from './Video';++const Layer = ({+ track,+ controller,+ items,+ selectedKeys,+}: {+ track: TimelineTrackData;+ controller: ReturnType<typeof useCanvasController>;+ items: CanvasSelectionItem[];+ selectedKeys: Set<string>;+}) => {+ const nodePathInfo = getCanvasSequenceNodePathInfo(track);+ const item: CanvasSelectionItem = {type: 'sequence', nodePathInfo};+ const key = getCanvasSelectionItemKey(item);+ const {hovered, onPointerEnter, onPointerLeave} = useCanvasSequenceHover(+ controller.hover,+ nodePathInfo,+ 'timeline',+ );++ return (+ <button+ aria-pressed={selectedKeys.has(key)}+ onPointerEnter={onPointerEnter}+ onPointerLeave={onPointerLeave}+ onClick={(event) => controller.selection.select(+ item,+ {shiftKey: event.shiftKey, toggleKey: event.metaKey || event.ctrlKey},+ items,+ )}+ >+ {hovered ? 'β ' : ''}{track.sequence.displayName ?? track.sequence.type}+ </button>+ );+};++export const Editor = () => {+ const controller = useCanvasController();+ const tracks = useSyncExternalStore(+ controller.timeline.subscribe,+ controller.timeline.getSnapshot,+ controller.timeline.getSnapshot,+ );+ const selection = useCanvasSelection(controller.selection);+ const items: CanvasSelectionItem[] = tracks.map((track) => ({+ type: 'sequence',+ nodePathInfo: getCanvasSequenceNodePathInfo(track),+ }));+ const selectedKeys = new Set(selection.selectedItems.map(getCanvasSelectionItemKey));++ return (+ <>+ <Canvas+ controller={controller}+ showOutlines+ component={Video}+ compositionWidth={1920}+ compositionHeight={1080}+ durationInFrames={150}+ fps={30}+ />+ <div>+ {tracks.map((track) => (+ <Layer+ key={track.sequence.id}+ track={track}+ controller={controller}+ items={items}+ selectedKeys={selectedKeys}+ />+ ))}+ </div>+ </>+ );+};+```++The timeline contains registered [`<Sequence>`](/docs/sequence) and other sequence tracks from the mounted composition. The Canvas does not edit source files or provide timeline controls; your interface owns those actions.++## Selection identity++The built-in [`getCanvasSequenceNodePathInfo()`](/docs/canvas/get-canvas-sequence-node-path-info) uses a source identity when available. Otherwise it falls back to a mounted sequence ID, which can change after a remount. If your editor tracks source nodes, pass a custom `resolveSequenceNodePathInfo` to `<Canvas>` and use the same resolver for layer items. Return `null` for tracks that should not be selectable.++An outline requires a registered DOM element. A `<Sequence layout="none">` has no outline of its own.++## APIs++import {TableOfContents} from './table-of-contents';++<TableOfContents />++## License++[Remotion License](/docs/license)diff --git a/packages/docs/docs/canvas/table-of-contents.tsx b/packages/docs/docs/canvas/table-of-contents.tsxnew file mode 100644index 0000000000..b2800b3101--- /dev/null+++ b/packages/docs/docs/canvas/table-of-contents.tsx@@ -0,0 +1,52 @@+import React from 'react';+import {Grid} from '../../components/TableOfContents/Grid';+import {TOCItem} from '../../components/TableOfContents/TOCItem';++export const TableOfContents: React.FC = () => {+ return (+ <div>+ <Grid>+ <TOCItem link="/docs/canvas/canvas">+ <strong>{'<Canvas>'}</strong>+ <div>Preview a composition with optional selection outlines</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/create-canvas-controller">+ <strong>createCanvasController()</strong>+ <div>Connect the canvas, timeline, selection, and hover</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/use-canvas-controller">+ <strong>useCanvasController()</strong>+ <div>Create a stable controller in a React component</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/create-canvas-selection-controller">+ <strong>createCanvasSelectionController()</strong>+ <div>Create a standalone selection store</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/create-canvas-hover-controller">+ <strong>createCanvasHoverController()</strong>+ <div>Create a standalone hover store</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/use-canvas-selection">+ <strong>useCanvasSelection()</strong>+ <div>Subscribe to selected layers and other items</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/use-canvas-sequence-hover">+ <strong>useCanvasSequenceHover()</strong>+ <div>Synchronize hover between a layer list and the canvas</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/use-canvas-hover">+ <strong>useCanvasHover()</strong>+ <div>Subscribe to the current hovered sequence</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/get-canvas-sequence-node-path-info">+ <strong>getCanvasSequenceNodePathInfo()</strong>+ <div>Resolve a timeline track's selection identity</div>+ </TOCItem>+ <TOCItem link="/docs/canvas/get-canvas-selection-item-key">+ <strong>getCanvasSelectionItemKey()</strong>+ <div>Compare selection items by identity</div>+ </TOCItem>+ </Grid>+ </div>+ );+};diff --git a/packages/docs/docs/canvas/use-canvas-controller.mdx b/packages/docs/docs/canvas/use-canvas-controller.mdxnew file mode 100644index 0000000000..b1a05f061f--- /dev/null+++ b/packages/docs/docs/canvas/use-canvas-controller.mdx@@ -0,0 +1,36 @@+---+image: /generated/articles-docs-canvas-use-canvas-controller.png+title: useCanvasController()+crumb: '@remotion/canvas'+---++# useCanvasController()<AvailableFrom v="4.0.527" />++Creates one [`CanvasController`](/docs/canvas/create-canvas-controller) for a React component and returns the same object on later renders. Import it from `@remotion/canvas`.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```tsx title="Preview.tsx"+import {Canvas, useCanvasController} from '@remotion/canvas';+import {Video} from './Video';++export const Preview = () => {+ const controller = useCanvasController();+ return <Canvas controller={controller} component={Video} compositionWidth={1920} compositionHeight={1080} durationInFrames={150} fps={30} />;+};+```++The hook takes no arguments. Share its returned controller with your layer list and other editor controls. Mount one `<Canvas>` per controller: the Canvas owns that controller's timeline snapshot and clears it on unmount.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`createCanvasController()`](/docs/canvas/create-canvas-controller)+- [`<Canvas>`](/docs/canvas/canvas)diff --git a/packages/docs/docs/canvas/use-canvas-hover.mdx b/packages/docs/docs/canvas/use-canvas-hover.mdxnew file mode 100644index 0000000000..f566003b4d--- /dev/null+++ b/packages/docs/docs/canvas/use-canvas-hover.mdx@@ -0,0 +1,57 @@+---+image: /generated/articles-docs-canvas-use-canvas-hover.png+title: useCanvasHover()+crumb: '@remotion/canvas'+---++# useCanvasHover()<AvailableFrom v="4.0.527" />++Subscribes to the current hovered sequence in a React component. Import it from `@remotion/canvas`.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```tsx title="HoverStatus.tsx"+import {useCanvasHover, type CanvasController} from '@remotion/canvas';++export const HoverStatus = ({controller}: {controller: CanvasController}) => {+ const hover = useCanvasHover(controller.hover);+ return <span>{hover ? `Hover from ${hover.source}` : 'No hover'}</span>;+};+```++## Parameter++### controller++A `CanvasHoverController`, usually `controller.hover` from [`useCanvasController()`](/docs/canvas/use-canvas-controller).++## Return value++A `CanvasHover` object or `null`.++### key++The identity of the hovered mounted sequence instance.++### nodePathKey++The source node identity shared by instances of that source node.++### source++`'canvas'` or `'timeline'`, indicating which surface set the hover.++For a single layer row, use [`useCanvasSequenceHover()`](/docs/canvas/use-canvas-sequence-hover) instead. It returns a boolean and pointer handlers for that row.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`useCanvasSequenceHover()`](/docs/canvas/use-canvas-sequence-hover)+- [`createCanvasController()`](/docs/canvas/create-canvas-controller)diff --git a/packages/docs/docs/canvas/use-canvas-selection.mdx b/packages/docs/docs/canvas/use-canvas-selection.mdxnew file mode 100644index 0000000000..9f0b5645d6--- /dev/null+++ b/packages/docs/docs/canvas/use-canvas-selection.mdx@@ -0,0 +1,53 @@+---+image: /generated/articles-docs-canvas-use-canvas-selection.png+title: useCanvasSelection()+crumb: '@remotion/canvas'+---++# useCanvasSelection()<AvailableFrom v="4.0.527" />++Subscribes a React component to a canvas selection controller. Import it from `@remotion/canvas`.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```tsx title="SelectionCount.tsx"+import {useCanvasSelection, type CanvasController} from '@remotion/canvas';++export const SelectionCount = ({controller}: {controller: CanvasController}) => {+ const {selectedItems} = useCanvasSelection(controller.selection);+ return <span>{selectedItems.length} selected</span>;+};+```++## Parameter++### controller++A `CanvasSelectionController`, usually `controller.selection` from [`useCanvasController()`](/docs/canvas/use-canvas-controller).++## Return value++A `CanvasSelectionSnapshot` with the following properties.++### selectedItems++A readonly array of `CanvasSelectionItem` values. An item has a `type` discriminator. The `sequence` variant contains `nodePathInfo`; other variants represent a sequence property, effect, keyframe, easing segment, or guide. Use [`getCanvasSelectionItemKey()`](/docs/canvas/get-canvas-selection-item-key) to compare items by identity.++### anchor++The `CanvasSelectionItem` used as the starting point for a subsequent Shift selection, or `null` when there is no anchor.++The controller's `select()` method accepts `shiftKey`, `toggleKey`, and the ordered selectable items. See [`createCanvasController()`](/docs/canvas/create-canvas-controller#select).++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`createCanvasController()`](/docs/canvas/create-canvas-controller)+- [`getCanvasSelectionItemKey()`](/docs/canvas/get-canvas-selection-item-key)diff --git a/packages/docs/docs/canvas/use-canvas-sequence-hover.mdx b/packages/docs/docs/canvas/use-canvas-sequence-hover.mdxnew file mode 100644index 0000000000..dac2dbb00d--- /dev/null+++ b/packages/docs/docs/canvas/use-canvas-sequence-hover.mdx@@ -0,0 +1,83 @@+---+image: /generated/articles-docs-canvas-use-canvas-sequence-hover.png+title: useCanvasSequenceHover()+crumb: '@remotion/canvas'+---++# useCanvasSequenceHover()<AvailableFrom v="4.0.527" />++Connects one layer row to the shared canvas hover state. Import it from `@remotion/canvas`.++:::warning++_Experimental API_: This package is not stable. Its public API may change without a major version bump.++:::++```tsx title="LayerRow.tsx"+import {+ useCanvasSequenceHover,+ type CanvasController,+ type TimelineTrackData,+ getCanvasSequenceNodePathInfo,+} from '@remotion/canvas';++export const LayerRow = ({controller, track}: {+ controller: CanvasController;+ track: TimelineTrackData;+}) => {+ const {hovered, onPointerEnter, onPointerLeave} = useCanvasSequenceHover(+ controller.hover,+ getCanvasSequenceNodePathInfo(track),+ 'timeline',+ );+ return (+ <button+ onPointerEnter={onPointerEnter}+ onPointerLeave={onPointerLeave}+ onFocus={onPointerEnter}+ onBlur={onPointerLeave}+ style={{background: hovered ? '#dbeafe' : 'transparent'}}+ >+ {track.sequence.displayName ?? track.sequence.type}+ </button>+ );+};+```++## Parameters++### controller++The `CanvasHoverController`, normally `controller.hover` from [`useCanvasController()`](/docs/canvas/use-canvas-controller).++### nodePathInfo++The track's `SequenceNodePathInfo`, or `null` for a row that cannot be hovered. Resolve it with [`getCanvasSequenceNodePathInfo()`](/docs/canvas/get-canvas-sequence-node-path-info) or the same custom resolver passed to [`<Canvas>`](/docs/canvas/canvas#resolvesequencenodepathinfo).++### source++`'timeline'` for a layer list or `'canvas'` for an overlay. The source is used when clearing hover so one surface does not clear the other surface's state.++## Return value++### hovered++A boolean indicating whether this source node is hovered. Multiple mounted instances with the same source identity can be highlighted together.++### onPointerEnter++Call when the pointer enters the row, or when a keyboard focus should highlight it.++### onPointerLeave++Call when the pointer leaves the row or it loses focus. It clears hover only if this hook still owns the current hover state.++## Compatibility++<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering player studio="" hideServers />++## See also++- [`useCanvasHover()`](/docs/canvas/use-canvas-hover)+- [`<Canvas>`](/docs/canvas/canvas)diff --git a/packages/docs/package.json b/packages/docs/package.jsonindex 8db60f742f..bde9f4da6e 100644--- a/packages/docs/package.json+++ b/packages/docs/package.json@@ -52,6 +52,7 @@"@remotion/browser-studio": "workspace:*","@remotion/bundler": "workspace:*","@remotion/captions": "workspace:*",+ "@remotion/canvas": "workspace:*","@remotion/cli": "workspace:*","@remotion/cloudrun": "workspace:*","@remotion/convert": "workspace:*",diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.tsindex 96073a98ce..d194998964 100644--- a/packages/docs/sidebars.ts+++ b/packages/docs/sidebars.ts@@ -2044,6 +2044,28 @@ const sidebars: SidebarsConfig = {],},],+ canvasSidebar: [+ {+ type: 'category',+ label: '@remotion/canvas',+ link: {+ type: 'doc',+ id: 'canvas/index',+ },+ items: [+ 'canvas/canvas',+ 'canvas/create-canvas-controller',+ 'canvas/use-canvas-controller',+ 'canvas/create-canvas-selection-controller',+ 'canvas/create-canvas-hover-controller',+ 'canvas/use-canvas-selection',+ 'canvas/use-canvas-sequence-hover',+ 'canvas/use-canvas-hover',+ 'canvas/get-canvas-sequence-node-path-info',+ 'canvas/get-canvas-selection-item-key',+ ],+ },+ ],codemodsSidebar: [{type: 'category',diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.tsindex a8a940d1c0..d17693fbc8 100644--- a/packages/docs/src/data/articles.ts+++ b/packages/docs/src/data/articles.ts@@ -657,6 +657,105 @@ export const articles = [noAi: false,slug: 'canvas-capture/installation',},+ {+ id: 'canvas/canvas',+ title: '<Canvas>',+ relativePath: 'docs/canvas/canvas.mdx',+ compId: 'articles-docs-canvas-canvas',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/canvas',+ },+ {+ id: 'canvas/create-canvas-controller',+ title: 'createCanvasController()',+ relativePath: 'docs/canvas/create-canvas-controller.mdx',+ compId: 'articles-docs-canvas-create-canvas-controller',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/create-canvas-controller',+ },+ {+ id: 'canvas/create-canvas-hover-controller',+ title: 'createCanvasHoverController()',+ relativePath: 'docs/canvas/create-canvas-hover-controller.mdx',+ compId: 'articles-docs-canvas-create-canvas-hover-controller',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/create-canvas-hover-controller',+ },+ {+ id: 'canvas/create-canvas-selection-controller',+ title: 'createCanvasSelectionController()',+ relativePath: 'docs/canvas/create-canvas-selection-controller.mdx',+ compId: 'articles-docs-canvas-create-canvas-selection-controller',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/create-canvas-selection-controller',+ },+ {+ id: 'canvas/get-canvas-selection-item-key',+ title: 'getCanvasSelectionItemKey()',+ relativePath: 'docs/canvas/get-canvas-selection-item-key.mdx',+ compId: 'articles-docs-canvas-get-canvas-selection-item-key',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/get-canvas-selection-item-key',+ },+ {+ id: 'canvas/get-canvas-sequence-node-path-info',+ title: 'getCanvasSequenceNodePathInfo()',+ relativePath: 'docs/canvas/get-canvas-sequence-node-path-info.mdx',+ compId: 'articles-docs-canvas-get-canvas-sequence-node-path-info',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/get-canvas-sequence-node-path-info',+ },+ {+ id: 'canvas/index',+ title: '@remotion/canvas',+ relativePath: 'docs/canvas/index.mdx',+ compId: 'articles-docs-canvas-index',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/index',+ },+ {+ id: 'canvas/use-canvas-controller',+ title: 'useCanvasController()',+ relativePath: 'docs/canvas/use-canvas-controller.mdx',+ compId: 'articles-docs-canvas-use-canvas-controller',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/use-canvas-controller',+ },+ {+ id: 'canvas/use-canvas-hover',+ title: 'useCanvasHover()',+ relativePath: 'docs/canvas/use-canvas-hover.mdx',+ compId: 'articles-docs-canvas-use-canvas-hover',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/use-canvas-hover',+ },+ {+ id: 'canvas/use-canvas-selection',+ title: 'useCanvasSelection()',+ relativePath: 'docs/canvas/use-canvas-selection.mdx',+ compId: 'articles-docs-canvas-use-canvas-selection',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/use-canvas-selection',+ },+ {+ id: 'canvas/use-canvas-sequence-hover',+ title: 'useCanvasSequenceHover()',+ relativePath: 'docs/canvas/use-canvas-sequence-hover.mdx',+ compId: 'articles-docs-canvas-use-canvas-sequence-hover',+ crumb: '@remotion/canvas',+ noAi: false,+ slug: 'canvas/use-canvas-sequence-hover',+ },{id: 'canvasimage',title: '<CanvasImage>',diff --git a/packages/docs/static/generated/articles-docs-canvas-canvas.png b/packages/docs/static/generated/articles-docs-canvas-canvas.pngnew file mode 100644index 0000000000..0400acffe6Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-canvas.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-create-canvas-controller.png b/packages/docs/static/generated/articles-docs-canvas-create-canvas-controller.pngnew file mode 100644index 0000000000..6b0def897dBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-create-canvas-controller.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-create-canvas-hover-controller.png b/packages/docs/static/generated/articles-docs-canvas-create-canvas-hover-controller.pngnew file mode 100644index 0000000000..969c82f395Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-create-canvas-hover-controller.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-create-canvas-selection-controller.png b/packages/docs/static/generated/articles-docs-canvas-create-canvas-selection-controller.pngnew file mode 100644index 0000000000..4e8f12c74bBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-create-canvas-selection-controller.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-get-canvas-selection-item-key.png b/packages/docs/static/generated/articles-docs-canvas-get-canvas-selection-item-key.pngnew file mode 100644index 0000000000..0f18464f45Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-get-canvas-selection-item-key.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-get-canvas-sequence-node-path-info.png b/packages/docs/static/generated/articles-docs-canvas-get-canvas-sequence-node-path-info.pngnew file mode 100644index 0000000000..6fff4a513fBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-get-canvas-sequence-node-path-info.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-index.png b/packages/docs/static/generated/articles-docs-canvas-index.pngnew file mode 100644index 0000000000..9ede7da51aBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-index.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-controller.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-controller.pngnew file mode 100644index 0000000000..bcccbec1edBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-controller.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-hover.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-hover.pngnew file mode 100644index 0000000000..6d2eedb6e8Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-hover.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-selection.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-selection.pngnew file mode 100644index 0000000000..382a3b8bedBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-selection.png differdiff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-sequence-hover.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-sequence-hover.pngnew file mode 100644index 0000000000..746af5e57aBinary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-sequence-hover.png differdiff --git a/packages/studio/bundle.ts b/packages/studio/bundle.tsindex f0fc881340..fbe9826d0d 100644--- a/packages/studio/bundle.ts+++ b/packages/studio/bundle.ts@@ -4,6 +4,7 @@ const external = ['react','remotion','@remotion/canvas',+ '@remotion/canvas/internal','react-dom','react','@remotion/media-utils',diff --git a/packages/studio/src/components/NewComposition/NewComposition.tsx b/packages/studio/src/components/NewComposition/NewComposition.tsxindex 9e3ac8fc39..5ffc9f3a66 100644--- a/packages/studio/src/components/NewComposition/NewComposition.tsx+++ b/packages/studio/src/components/NewComposition/NewComposition.tsx@@ -1,4 +1,4 @@-import {sortItemsByCommitOrder} from '@remotion/canvas';+import {sortItemsByCommitOrder} from '@remotion/canvas/internal';import type {ChangeEventHandler,Dispatch,diff --git a/packages/studio/src/components/SelectedOutlineOverlay.tsx b/packages/studio/src/components/SelectedOutlineOverlay.tsxindex 6a813890ff..d8d69e0b11 100644--- a/packages/studio/src/components/SelectedOutlineOverlay.tsx+++ b/packages/studio/src/components/SelectedOutlineOverlay.tsx@@ -5,7 +5,7 @@ import {getCanvasActiveOutlineTargets,getCanvasOutlineActivity,getCanvasOutlineLayoutTargets,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';import {PlayerInternals} from '@remotion/player';import React, {useCallback,diff --git a/packages/studio/src/components/SelectedOutlinePolygon.tsx b/packages/studio/src/components/SelectedOutlinePolygon.tsxindex 2b8f088de9..ee3e8d5c27 100644--- a/packages/studio/src/components/SelectedOutlinePolygon.tsx+++ b/packages/studio/src/components/SelectedOutlinePolygon.tsx@@ -1,7 +1,7 @@import {CanvasOutlinePolygon,handleCanvasOutlinePointerDown,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';import React, {useContext, useMemo, useRef, useState} from 'react';import {Internals} from 'remotion';import {StudioServerConnectionCtx} from '../helpers/client-id';diff --git a/packages/studio/src/components/SelectedOutlineRenderer.tsx b/packages/studio/src/components/SelectedOutlineRenderer.tsxindex 78a01f3a66..2c0e88432b 100644--- a/packages/studio/src/components/SelectedOutlineRenderer.tsx+++ b/packages/studio/src/components/SelectedOutlineRenderer.tsx@@ -1,4 +1,4 @@-import {useCanvasOutlines} from '@remotion/canvas';+import {useCanvasOutlines} from '@remotion/canvas/internal';import React, {useCallback,useContext,diff --git a/packages/studio/src/components/Timeline/TimelineSelection.tsx b/packages/studio/src/components/Timeline/TimelineSelection.tsxindex ce33380c27..65ba7bd290 100644--- a/packages/studio/src/components/Timeline/TimelineSelection.tsx+++ b/packages/studio/src/components/Timeline/TimelineSelection.tsx@@ -8,7 +8,7 @@ import {type CanvasSelectionInteraction,type CanvasSelectionItem,type CanvasSelectionSnapshot,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';import {canEditEasingForInterpolationFunction,stringifySequenceExpandedRowKey,diff --git a/packages/studio/src/components/Timeline/TimelineSequence.tsx b/packages/studio/src/components/Timeline/TimelineSequence.tsxindex e1097af69b..8364d7e431 100644--- a/packages/studio/src/components/Timeline/TimelineSequence.tsx+++ b/packages/studio/src/components/Timeline/TimelineSequence.tsx@@ -1,8 +1,8 @@import {getTimelineVisibleDuration,getTimelineVisibleStart,-} from '@remotion/canvas';-import type {TimelineTrackData} from '@remotion/canvas';+} from '@remotion/canvas/internal';+import type {TimelineTrackData} from '@remotion/canvas/internal';import React, {useCallback,useContext,diff --git a/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx b/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsxindex 31ac0edf6d..6c64e7fee6 100644--- a/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx+++ b/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx@@ -1,7 +1,7 @@import {getParentSequencePlaybackRate,sortItemsByCommitOrder,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';import {stringifySequenceExpandedRowKey,stringifySequenceSubscriptionKey,diff --git a/packages/studio/src/components/selected-outline-geometry.ts b/packages/studio/src/components/selected-outline-geometry.tsindex 3f5fd3c69b..0a2177a8a2 100644--- a/packages/studio/src/components/selected-outline-geometry.ts+++ b/packages/studio/src/components/selected-outline-geometry.ts@@ -1,9 +1,9 @@-import type {CanvasOutlinePoint as OutlinePoint} from '@remotion/canvas';+import type {CanvasOutlinePoint as OutlinePoint} from '@remotion/canvas/internal';export type {CanvasOutline as SelectedOutline,CanvasOutlinePoint as OutlinePoint,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';export const clamp = (value: number, min: number, max: number): number => {return Math.min(max, Math.max(min, value));diff --git a/packages/studio/src/components/selected-outline-measurement.ts b/packages/studio/src/components/selected-outline-measurement.tsindex 81f06c21e5..49794d26c3 100644--- a/packages/studio/src/components/selected-outline-measurement.ts+++ b/packages/studio/src/components/selected-outline-measurement.ts@@ -1,4 +1,4 @@-import {getCanvasSelectableOutlines} from '@remotion/canvas';+import {getCanvasSelectableOutlines} from '@remotion/canvas/internal';import type {_InternalTypes, OverrideIdToNodePaths, TSequence} from 'remotion';import {calculateTimeline} from '../helpers/calculate-timeline';import {BLACK, WHITE} from '../helpers/colors';@@ -29,7 +29,7 @@ export {cropCanvasOutlinePoints as cropOutlinePoints,getTransformedSvgViewportPoints,measureCanvasOutlineTargets as measureOutlineTargets,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';export const pointToString = (point: OutlinePoint) => `${point.x},${point.y}`;diff --git a/packages/studio/src/components/selected-outline-order.ts b/packages/studio/src/components/selected-outline-order.tsindex 1db8887490..4509e977c5 100644--- a/packages/studio/src/components/selected-outline-order.ts+++ b/packages/studio/src/components/selected-outline-order.ts@@ -1 +1 @@-export {orderCanvasOutlinesForRendering as orderOutlinesForRendering} from '@remotion/canvas';+export {orderCanvasOutlinesForRendering as orderOutlinesForRendering} from '@remotion/canvas/internal';diff --git a/packages/studio/src/components/selected-outline-types.ts b/packages/studio/src/components/selected-outline-types.tsindex 6de0bf5386..a7b9e0529f 100644--- a/packages/studio/src/components/selected-outline-types.ts+++ b/packages/studio/src/components/selected-outline-types.ts@@ -2,7 +2,7 @@ import type {CanvasOutlineCrop,CanvasOutlineLayoutTarget,CanvasSelectableOutline,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';import type {CanUpdateSequencePropStatus,CanUpdateSequencePropStatusKeyframed,diff --git a/packages/studio/src/components/selected-outline-uv.ts b/packages/studio/src/components/selected-outline-uv.tsindex 18357140cd..309c9f7093 100644--- a/packages/studio/src/components/selected-outline-uv.ts+++ b/packages/studio/src/components/selected-outline-uv.ts@@ -1,4 +1,4 @@-import {getCanvasOutlinePoint as getUvHandlePosition} from '@remotion/canvas';+import {getCanvasOutlinePoint as getUvHandlePosition} from '@remotion/canvas/internal';import type {CanUpdateSequencePropStatusKeyframed,CanUpdateSequencePropStatusStatic,@@ -27,7 +27,7 @@ import {export {getCanvasOutlinePoint as getUvHandlePosition,getCanvasOutlineUv as getUvCoordinateForPoint,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';export type UvCoordinate = readonly [number, number];diff --git a/packages/studio/src/components/use-selected-outline-control-target.ts b/packages/studio/src/components/use-selected-outline-control-target.tsindex 0dbe6941a0..27cb77abb4 100644--- a/packages/studio/src/components/use-selected-outline-control-target.ts+++ b/packages/studio/src/components/use-selected-outline-control-target.ts@@ -1,4 +1,4 @@-import {useCanvasSequenceHover} from '@remotion/canvas';+import {useCanvasSequenceHover} from '@remotion/canvas/internal';import React, {useContext, useLayoutEffect, useRef} from 'react';import {TimelineSequenceHoverContext} from '../state/timeline-sequence-hover';import type {diff --git a/packages/studio/src/helpers/calculate-timeline.ts b/packages/studio/src/helpers/calculate-timeline.tsindex 6283223621..77186a6475 100644--- a/packages/studio/src/helpers/calculate-timeline.ts+++ b/packages/studio/src/helpers/calculate-timeline.ts@@ -1 +1 @@-export {calculateTimeline} from '@remotion/canvas';+export {calculateTimeline} from '@remotion/canvas/internal';diff --git a/packages/studio/src/helpers/create-folder-tree.ts b/packages/studio/src/helpers/create-folder-tree.tsindex 579e3f1cd6..6e41e1b8d2 100644--- a/packages/studio/src/helpers/create-folder-tree.ts+++ b/packages/studio/src/helpers/create-folder-tree.ts@@ -1,4 +1,4 @@-import {sortItemsByCommitOrder} from '@remotion/canvas';+import {sortItemsByCommitOrder} from '@remotion/canvas/internal';import type {_InternalTypes, StaticFile, TFolder} from 'remotion';import type {CompositionSelectorItemType} from '../components/CompositionSelectorItem';import {openFolderKey} from './persist-open-folders';diff --git a/packages/studio/src/helpers/get-connected-compositions.ts b/packages/studio/src/helpers/get-connected-compositions.tsindex 53bed258e0..59f20b4241 100644--- a/packages/studio/src/helpers/get-connected-compositions.ts+++ b/packages/studio/src/helpers/get-connected-compositions.ts@@ -1 +1 @@-export {getConnectedCompositions} from '@remotion/canvas';+export {getConnectedCompositions} from '@remotion/canvas/internal';diff --git a/packages/studio/src/helpers/get-sequence-visible-range.ts b/packages/studio/src/helpers/get-sequence-visible-range.tsindex 0b0ee393c9..48d0300c00 100644--- a/packages/studio/src/helpers/get-sequence-visible-range.ts+++ b/packages/studio/src/helpers/get-sequence-visible-range.ts@@ -4,4 +4,4 @@ export {getCascadedStartWithTrim,getTimelineVisibleDuration,getTimelineVisibleStart,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';diff --git a/packages/studio/src/helpers/get-timeline-nestedness.ts b/packages/studio/src/helpers/get-timeline-nestedness.tsindex 9f3a57edc5..61d60cb0c3 100644--- a/packages/studio/src/helpers/get-timeline-nestedness.ts+++ b/packages/studio/src/helpers/get-timeline-nestedness.ts@@ -1 +1 @@-export {getTimelineNestedLevel} from '@remotion/canvas';+export {getTimelineNestedLevel} from '@remotion/canvas/internal';diff --git a/packages/studio/src/helpers/get-timeline-sequence-sort-key.ts b/packages/studio/src/helpers/get-timeline-sequence-sort-key.tsindex 268ea16faa..54abb5b936 100644--- a/packages/studio/src/helpers/get-timeline-sequence-sort-key.ts+++ b/packages/studio/src/helpers/get-timeline-sequence-sort-key.ts@@ -1,6 +1,6 @@-export {getTimelineSequenceSortKey} from '@remotion/canvas';+export {getTimelineSequenceSortKey} from '@remotion/canvas/internal';export type {SequenceNodePathInfo,TimelineTrackData,TimelineTrackWithOriginalTimings,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';diff --git a/packages/studio/src/helpers/timeline-node-path-key.ts b/packages/studio/src/helpers/timeline-node-path-key.tsindex 38564a826e..c6c7c35668 100644--- a/packages/studio/src/helpers/timeline-node-path-key.ts+++ b/packages/studio/src/helpers/timeline-node-path-key.ts@@ -1,7 +1,7 @@import {stringifySequenceExpandedRowKey} from '@remotion/studio-shared';import type {SequenceNodePathInfo} from './get-timeline-sequence-sort-key';-export {timelineSequenceNodePathToKey} from '@remotion/canvas';+export {timelineSequenceNodePathToKey} from '@remotion/canvas/internal';export const timelineNodePathInfoToKey = (info: SequenceNodePathInfo): string =>[diff --git a/packages/studio/src/helpers/use-runtime-values.ts b/packages/studio/src/helpers/use-runtime-values.tsindex f2fedddefb..74e353319a 100644--- a/packages/studio/src/helpers/use-runtime-values.ts+++ b/packages/studio/src/helpers/use-runtime-values.ts@@ -81,4 +81,4 @@ export const useRuntimeValueSelector = <T>({);};-export {useCanvasRuntimeValueSnapshots as useRuntimeValueSnapshots} from '@remotion/canvas';+export {useCanvasRuntimeValueSnapshots as useRuntimeValueSnapshots} from '@remotion/canvas/internal';diff --git a/packages/studio/src/state/timeline-sequence-hover.ts b/packages/studio/src/state/timeline-sequence-hover.tsindex 6add9040be..54e3df8013 100644--- a/packages/studio/src/state/timeline-sequence-hover.ts+++ b/packages/studio/src/state/timeline-sequence-hover.ts@@ -1,10 +1,13 @@-import type {CanvasHover, CanvasHoverController} from '@remotion/canvas';+import type {+ CanvasHover,+ CanvasHoverController,+} from '@remotion/canvas/internal';import {createCanvasHoverController,useCanvasHover,useCanvasSequenceHover,useIsCanvasSequenceHovered,-} from '@remotion/canvas';+} from '@remotion/canvas/internal';import {createContext, useContext} from 'react';import type {SequenceNodePathInfo} from '../helpers/get-timeline-sequence-sort-key';