Skip to content

πŸŽ₯ Make videos programmatically with React

`@remotion/canvas`: Define and document public authoring API

Jonny Burger4c8ce226636f
diff --git a/bun.lock b/bun.lock
index 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.md
index 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.ts
index 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.json
index 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.ts
index 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.ts
new file mode 100644
index 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.mdx
new file mode 100644
index 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'
+---
+
+# &lt;Canvas&gt;<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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.json
index 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.ts
index 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.ts
index 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.png
new file mode 100644
index 0000000000..0400acffe6
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-canvas.png differ
diff --git a/packages/docs/static/generated/articles-docs-canvas-create-canvas-controller.png b/packages/docs/static/generated/articles-docs-canvas-create-canvas-controller.png
new file mode 100644
index 0000000000..6b0def897d
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-create-canvas-controller.png differ
diff --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.png
new file mode 100644
index 0000000000..969c82f395
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-create-canvas-hover-controller.png differ
diff --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.png
new file mode 100644
index 0000000000..4e8f12c74b
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-create-canvas-selection-controller.png differ
diff --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.png
new file mode 100644
index 0000000000..0f18464f45
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-get-canvas-selection-item-key.png differ
diff --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.png
new file mode 100644
index 0000000000..6fff4a513f
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-get-canvas-sequence-node-path-info.png differ
diff --git a/packages/docs/static/generated/articles-docs-canvas-index.png b/packages/docs/static/generated/articles-docs-canvas-index.png
new file mode 100644
index 0000000000..9ede7da51a
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-index.png differ
diff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-controller.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-controller.png
new file mode 100644
index 0000000000..bcccbec1ed
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-controller.png differ
diff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-hover.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-hover.png
new file mode 100644
index 0000000000..6d2eedb6e8
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-hover.png differ
diff --git a/packages/docs/static/generated/articles-docs-canvas-use-canvas-selection.png b/packages/docs/static/generated/articles-docs-canvas-use-canvas-selection.png
new file mode 100644
index 0000000000..382a3b8bed
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-selection.png differ
diff --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.png
new file mode 100644
index 0000000000..746af5e57a
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-canvas-use-canvas-sequence-hover.png differ
diff --git a/packages/studio/bundle.ts b/packages/studio/bundle.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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';