Skip to content

Open source CapCut alternative.

TypeScript

feat(site): ⌘C copies whatever the pointer is on into a prompt

David Le2c8c44b77470
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.md
index 5894f7ac..a0ddd14e 100644
--- a/docs/guides/cut/README.md
+++ b/docs/guides/cut/README.md
@@ -160,7 +160,11 @@ The AI assistant knows the editor through three surfaces: the catalog — tool d
**Teach the assistant in the same change.** When an editor feature lands, changes, or goes away, update those surfaces with it — usually by adding, updating, or deleting the matching tools and skills, and by extending the context snapshot when the feature adds user-visible state. A feature the catalog omits is invisible to the assistant, and a stale tool or skill is worse: the assistant confidently acts on behavior that no longer exists.
-**Everything the user can point at is referenceable.** Every entity the editor lets a user select or create — a clip, a keyframe, a mask, a sticker, a title, an effect, a generated asset, a library item — carries a stable id and joins the editor's one reference model. The ref is how an entity leaves its home surface: drag it onto a drop zone, copy it with ⌘C and paste it into the chat composer, or type its @handle in a prompt, and chat resolves it back to the live entity — "tighten @c2" reaches the real clip and the tools that edit it. When a feature adds a new kind of entity, wire its ref in the same change: a scope and handle among the mention candidates, copy and drag affordances where the entity renders, and tools that accept its id. An entity without a ref is invisible to chat.
+**Everything the user can point at is referenceable.** Every entity the editor lets a user select or create — a clip, a keyframe, a mask, a sticker, a title, an effect, a generated asset, a library item, a phone recording — carries a stable id and joins the editor's one reference model. The ref is how an entity leaves its home surface: drag it onto a drop zone, copy it with ⌘C and paste it into the chat composer, or type its @handle in a prompt, and chat resolves it back to the live entity — "tighten @c2" reaches the real clip and the tools that edit it.
+
+The catalogs are referenceable too: an effect, a transition style or a shape copied out of its panel pastes as a mention that carries the catalog id and the tool that places it, so "put a @"Cross fade transition" on that cut" names the exact treatment the user pointed at.
+
+⌘C is one keystroke with one implementation behind it. A card or tile says what it stands for, the copy handler picks whatever the pointer is on (falling back to what has focus), and it writes that ref's mention token — so what a tile's copy button copies and what the keystroke copies are the same string, on the library page, in the editor's panels, and in chat. When a feature adds a new kind of entity, wire its ref in the same change: a scope and handle among the mention candidates, copy and drag affordances where the entity renders, and tools that accept its id. An entity without a ref is invisible to chat.
## Where it lives
diff --git a/site/src/cut/components/ChatAssets.tsx b/site/src/cut/components/ChatAssets.tsx
index fd7d74a0..cfe64191 100644
--- a/site/src/cut/components/ChatAssets.tsx
+++ b/site/src/cut/components/ChatAssets.tsx
@@ -7,13 +7,12 @@ import { DropdownMenuItem } from "@/components/ui/dropdown-menu";
import { MEDIA_CORS } from "@/cut/lib/mediaCors";
import { clearAssetDrag, setAssetDragData, setChipDragImage } from "@/cut/lib/assetDrag";
import {
- projectRefs,
refFromAsset,
- refToken,
setRefDragData,
type AssetRef,
type AssetRefKind,
} from "@/cut/lib/assetRef";
+import { copyRefs, useRefCopy } from "@/cut/lib/refCopy";
import { useElapsed } from "@/cut/hooks/useElapsed";
import { useHoverPlay } from "@/cut/hooks/useHoverPlay";
import { useInView } from "@/cut/hooks/useInView";
@@ -56,10 +55,18 @@ export function ChatAssetCard({ item }: { item: AssetRef }) {
const asset = useEditor((s) =>
item.scope === "project" ? s.assets.find((a) => a.id === item.id) : undefined
);
+ // ⌘C over a chat card copies its mention token, so an asset the assistant
+ // made goes straight into the next prompt. The wrapper lays out as nothing —
+ // it is only somewhere for the copy registration to hang.
+ const copyRef = useRefCopy(() => [liveRef(item, asset)]);
// A project ref whose asset is gone has nothing left to preview.
if (item.scope === "project" && !asset) return null;
const Card = CHAT_CARDS[item.kind];
- return <Card item={item} asset={asset} />;
+ return (
+ <div ref={copyRef} className="contents">
+ <Card item={item} asset={asset} />
+ </div>
+ );
}
/** Chat card for a project asset id — how tool outputs name what they made. */
@@ -221,16 +228,7 @@ function ChatCardMenu({ asset, triggerClassName }: { asset: MediaAsset; triggerC
<Maximize2 /> Expand
</DropdownMenuItem>
<DropdownMenuItem
- onClick={() => {
- // The session handle (v2, i1) is derived, not stored — resolve
- // it at click time instead of subscribing every card to it.
- const live = projectRefs(useEditor.getState().assets).find(
- (r) => r.id === asset.id
- );
- void navigator.clipboard
- .writeText(refToken(live ?? refFromAsset(asset)))
- .catch(() => {});
- }}
+ onClick={() => copyRefs([refFromAsset(asset)])}
>
<Copy /> Copy reference
</DropdownMenuItem>
diff --git a/site/src/cut/components/Editor.tsx b/site/src/cut/components/Editor.tsx
index 319d009c..dad99688 100644
--- a/site/src/cut/components/Editor.tsx
+++ b/site/src/cut/components/Editor.tsx
@@ -21,6 +21,7 @@ import {
type ExportDoc,
} from "@/cut/lib/exportClient";
import { fileZoneAt, hasRefDrag, selectionRefTokens } from "@/cut/lib/assetRef";
+import { copyableRefs } from "@/cut/lib/refCopy";
import { startUpload } from "@/cut/lib/importQueue";
import { enrichAsset, importFileToProject, prepareImport } from "@/cut/lib/media";
import { clearCopiedFrame, copiedFrameFile, hasCopiedFrame } from "@/cut/lib/stageFrame";
@@ -937,6 +938,11 @@ export function Editor({
// element, transition, cue, or keyframe pastes into the chat
// composer as a reference.
if (!window.getSelection()?.toString()) {
+ // A card or tile under the pointer is the more deliberate pick, and
+ // the shared ⌘C path (lib/refCopy.ts) has already copied it off the
+ // same keystroke. The timeline clipboard keeps its last timeline
+ // copy, so ⌘V still pastes what was copied for the timeline.
+ if (copyableRefs().length > 0) return;
const token = selectionRefTokens(s);
if (token) void navigator.clipboard.writeText(token).catch(() => {});
// The newer copy owns the clipboard: a copied preview frame steps
diff --git a/site/src/cut/components/GeneratePanel.tsx b/site/src/cut/components/GeneratePanel.tsx
index 66ec8eb9..340dbae7 100644
--- a/site/src/cut/components/GeneratePanel.tsx
+++ b/site/src/cut/components/GeneratePanel.tsx
@@ -331,6 +331,7 @@ function JobRow({ job, handle }: { job: GenerateJob; handle?: string }) {
return (
<div
ref={tileRef}
+ data-pick-id={job.assetId ?? undefined}
className={cn("gen-job group relative overflow-hidden rounded-lg", picked && PICKED_RING)}
onMouseEnter={() => {
const v = videoRef.current;
diff --git a/site/src/cut/components/ImageGenPanel.tsx b/site/src/cut/components/ImageGenPanel.tsx
index 667cdd70..17d07beb 100644
--- a/site/src/cut/components/ImageGenPanel.tsx
+++ b/site/src/cut/components/ImageGenPanel.tsx
@@ -243,6 +243,7 @@ function GeneratedTile({
return (
<div
ref={tileRef}
+ data-pick-id={asset.id}
className={cn("group relative overflow-hidden rounded-lg", picked && PICKED_RING)}
>
<button
diff --git a/site/src/cut/components/LibraryView.tools.ts b/site/src/cut/components/LibraryView.tools.ts
index f579199f..043982fe 100644
--- a/site/src/cut/components/LibraryView.tools.ts
+++ b/site/src/cut/components/LibraryView.tools.ts
@@ -35,8 +35,11 @@ export const LIBRARY_TOOLS = [
{
name: "template_add",
description:
- "Re-materialize a Library template into the project: its media import as assets and its clips, overlays, titles, and captions land editable, exactly as saved (clip layers append to track 0; free-positioned parts line up at the playhead). Call it only when the user asked for the template in the cut.",
- inputSchema: obj({ id: str("Template id from library_list") }, ["id"]),
+ "Re-materialize a template into the project: its clips, overlays, titles, and captions land editable, exactly as saved (clip layers append to track 0; free-positioned parts line up at the playhead). A Library template's media import as assets on the way in; a template saved in this project's own Media reuses the media already here. Call it only when the user asked for the template in the cut.",
+ inputSchema: obj(
+ { id: str("Template id — from library_list, or the id carried by a template the user referenced") },
+ ["id"],
+ ),
},
{
name: "save_template",
diff --git a/site/src/cut/components/LibraryView.tsx b/site/src/cut/components/LibraryView.tsx
index 55e0df55..8ce205da 100644
--- a/site/src/cut/components/LibraryView.tsx
+++ b/site/src/cut/components/LibraryView.tsx
@@ -114,6 +114,8 @@ import { shapeBand } from "@/cut/lib/types";
import { useRevealFlash } from "@/cut/lib/refReveal";
import { formatTime } from "@/cut/lib/time";
import { cn } from "@/lib/utils";
+import { refFromLibrary } from "@/cut/lib/assetRef";
+import { useRefCopy } from "@/cut/lib/refCopy";
import { CopyNameLabel } from "./AssetRefs";
import { FontSpecimen } from "./FontSpecimen";
import {
@@ -662,6 +664,9 @@ export function LibraryView() {
const bothShelves = listed.length > 1;
const shown = all.filter((a) => (a.folderId ?? null) === openFolder);
+ // The picked run, built once for the whole grid: every card hands the same
+ // array to its drag and its ⌘C.
+ const pickedRun = shown.filter((a) => selected.has(a.id));
// Similar-shape tiles get their own band of wrapped rows, so a wide tile
// never shares a row with a tall one; audio and unmeasured assets band as
// squares. Order within and across bands follows the listing. An arrival
@@ -909,6 +914,7 @@ export function LibraryView() {
asset={a}
area={TILE_AREA}
selected={selected.has(a.id)}
+ dragGroup={pickedRun}
offline={!live(a.residency)}
// A live item opens in the viewer. Clicking one this browser
// can only remember is the moment something is actually
@@ -1052,6 +1058,15 @@ export function LibraryCard({
}) {
const videoRef = useRef<HTMLVideoElement>(null);
const { flash, attachReveal } = useRevealFlash("library", a.id);
+ // ⌘C over the card copies its mention token. A card inside the current
+ // selection carries the whole set, the same rule its drag follows. A font is
+ // used from the font menu, so it names nothing a prompt can point a tool
+ // at.
+ const copyRef = useRefCopy(() =>
+ (selected && dragGroup?.length ? dragGroup : [a])
+ .filter((x) => x.type !== "font")
+ .map(refFromLibrary),
+ );
// With one shelf listed, every card is on it — the badge would say nothing.
// Phone recordings all come up from the cloud, so they carry none either.
const bothShelves =
@@ -1098,7 +1113,10 @@ export function LibraryCard({
return (
<div
- ref={attachReveal}
+ ref={(el) => {
+ attachReveal(el);
+ copyRef(el);
+ }}
data-sel-id={a.id}
className="group flex flex-col"
draggable={!offline}
@@ -1170,7 +1188,7 @@ export function LibraryCard({
<CopyNameLabel
name={a.name}
dark
- mention={mention}
+ mention={false}
className="min-w-0 text-[11px] font-medium @[220px]:text-[13px]"
/>
{fontMeta && (
diff --git a/site/src/cut/components/SidePanel.tsx b/site/src/cut/components/SidePanel.tsx
index bf67d701..3216f67e 100644
--- a/site/src/cut/components/SidePanel.tsx
+++ b/site/src/cut/components/SidePanel.tsx
@@ -35,7 +35,13 @@ import {
setAssetDragData,
setObjectDragImage,
} from "@/cut/lib/assetDrag";
-import { draggingRef, useAssetDrop, type AssetRef } from "@/cut/lib/assetRef";
+import {
+ draggingRef,
+ refFromAsset,
+ useAssetDrop,
+ type AssetRef,
+} from "@/cut/lib/assetRef";
+import { useRefCopy } from "@/cut/lib/refCopy";
import { RefDropZone } from "./RefDropZone";
import { deleteExport, downloadProjectExport, revealExport } from "@/cut/lib/exportClient";
import { useExports, useWatchExportLands, type ExportJob } from "@/cut/lib/exportStore";
@@ -649,6 +655,8 @@ function ProjectFilesPanel({
// Which tiles are picked, so a sweep or a ⇧-click can hand the timeline a
// run of media in one drag. Anything that leaves the grid leaves the pick.
const { picked, setPicked, pick } = useTilePicks(assets.map((a) => a.id));
+ // Built once for the whole grid; each card hands the same array on.
+ const pickedIds = [...picked];
const templates = useEditor((s) => s.templates);
const exportOpen = useEditor((s) => s.exportOpen);
// A render that finishes in the background (dialog closed) drops a new file in
@@ -810,7 +818,7 @@ function ProjectFilesPanel({
projectId={projectId}
selected={picked.has(a.id)}
onSelect={(e) => pick(e, a.id, assets.map((x) => x.id))}
- dragGroup={[...picked]}
+ dragGroup={pickedIds}
/>
))}
{importing && (
@@ -1008,6 +1016,16 @@ function AssetCard({
const [confirmUses, setConfirmUses] = useState<number | null>(null);
const videoRef = useRef<HTMLVideoElement>(null);
const { flash, attachReveal } = useRevealFlash("project", asset.id);
+ // ⌘C over the card copies its mention token (`@v2`). A card inside the
+ // current pick carries the whole set, the same rule its drag follows.
+ const copyRef = useRefCopy(() => {
+ const all = useEditor.getState().assets;
+ const ids = selected && dragGroup?.length ? dragGroup : [asset.id];
+ return ids
+ .map((id) => all.find((x) => x.id === id))
+ .filter((x): x is MediaAsset => !!x)
+ .map(refFromAsset);
+ });
// A media-heavy project would open every one of these connections at once;
// the source waits until the tile has been scrolled near.
const [tileRef, seen] = useInView<HTMLDivElement>();
@@ -1043,7 +1061,10 @@ function AssetCard({
return (
<>
<div
- ref={attachReveal}
+ ref={(el) => {
+ attachReveal(el);
+ copyRef(el);
+ }}
data-sel-id={asset.id}
className="asset-card group flex flex-col gap-1.5 text-left"
title="Drag onto the timeline, or click + to add"
@@ -1362,6 +1383,8 @@ function LibraryPanel({ projectId }: { projectId: string }) {
// folder tile) a run of clips in one drag. Only what the open folder shows
// can be picked, so walking into another folder leaves its selection behind.
const { picked, setPicked, pick } = useTilePicks(shown.map((a) => a.id));
+ // Built once for the whole grid; each card hands the same array on.
+ const pickedRun = shown.filter((a) => picked.has(a.id));
// Let a clip be dragged onto a folder tile to file it (alongside the timeline
// drag payload the card already sets). The ghost is the card's picture, and
@@ -1534,7 +1557,7 @@ function LibraryPanel({ projectId }: { projectId: string }) {
mention
selected={picked.has(a.id)}
onClick={(e) => pick(e, a.id, shown.map((x) => x.id))}
- dragGroup={shown.filter((x) => picked.has(x.id))}
+ dragGroup={pickedRun}
// A font is used from the font menu; there is nothing to place.
onUse={
a.type === "font" ? undefined : () => void addLibraryAssetToProject(projectId, a)
diff --git a/site/src/cut/components/StockImagesPanel.tsx b/site/src/cut/components/StockImagesPanel.tsx
index d810b227..1e78eebd 100644
--- a/site/src/cut/components/StockImagesPanel.tsx
+++ b/site/src/cut/components/StockImagesPanel.tsx
@@ -3,6 +3,7 @@
import { useState } from "react";
import { ChevronLeft, ChevronRight, Maximize2, Search } from "lucide-react";
import { clearRefDrag, refFromStock, setRefDragData } from "@/cut/lib/assetRef";
+import { useRefCopy } from "@/cut/lib/refCopy";
import { setObjectDragImage } from "@/cut/lib/assetDrag";
import { useLightbox } from "@/cut/lib/lightbox";
import { useRevealEffect, useRevealFlash } from "@/cut/lib/refReveal";
@@ -153,9 +154,13 @@ function SectionHead({ title, onViewAll }: { title: string; onViewAll?: () => vo
* and it drags as an asset ref (chat attachment, generation reference). */
function StockTile({ item }: { item: StockImage }) {
const { flash, attachReveal } = useRevealFlash("stock", item.id);
+ const copyRef = useRefCopy(() => [refFromStock(item)]);
return (
<div
- ref={attachReveal}
+ ref={(el) => {
+ attachReveal(el);
+ copyRef(el);
+ }}
className={cn(
"group relative overflow-hidden rounded-lg",
flash && "ring-2 ring-[#0a84ff] ring-offset-1"
diff --git a/site/src/cut/components/StockMusicPanel.tsx b/site/src/cut/components/StockMusicPanel.tsx
index 97dea2b6..f4287f00 100644
--- a/site/src/cut/components/StockMusicPanel.tsx
+++ b/site/src/cut/components/StockMusicPanel.tsx
@@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from "react";
import { Pause, Play, Plus } from "lucide-react";
import { PeakStrip } from "@/cut/components/AudioPanel";
import { clearRefDrag, refFromStockMusic, setRefDragData } from "@/cut/lib/assetRef";
+import { useRefCopy } from "@/cut/lib/refCopy";
import { setObjectDragImage } from "@/cut/lib/assetDrag";
import { importStockMusic } from "@/cut/lib/media";
import { useMusicGen } from "@/cut/lib/musicGen";
@@ -115,8 +116,10 @@ function SampleCard({
onTogglePlay: () => void;
onAdd: () => void;
}) {
+ const copyRef = useRefCopy(() => [refFromStockMusic(sample)]);
return (
<div
+ ref={copyRef}
className="group flex cursor-grab flex-col overflow-hidden rounded-xl border border-border bg-muted/40"
draggable
onDragStart={(e) => {
diff --git a/site/src/cut/components/StockVideosPanel.tsx b/site/src/cut/components/StockVideosPanel.tsx
index fb21f26e..42856536 100644
--- a/site/src/cut/components/StockVideosPanel.tsx
+++ b/site/src/cut/components/StockVideosPanel.tsx
@@ -3,6 +3,7 @@
import { useRef, useState } from "react";
import { ChevronRight, Maximize2, Search } from "lucide-react";
import { clearRefDrag, refFromStockVideo, setRefDragData } from "@/cut/lib/assetRef";
+import { useRefCopy } from "@/cut/lib/refCopy";
import { setObjectDragImage } from "@/cut/lib/assetDrag";
import { useLightbox } from "@/cut/lib/lightbox";
import { useRevealEffect, useRevealFlash } from "@/cut/lib/refReveal";
@@ -211,9 +212,13 @@ function Grid({ items }: { items: StockVideo[] }) {
function StockTile({ item }: { item: StockVideo }) {
const videoRef = useRef<HTMLVideoElement>(null);
const { flash, attachReveal } = useRevealFlash("stock", item.id);
+ const copyRef = useRefCopy(() => [refFromStockVideo(item)]);
return (
<div
- ref={attachReveal}
+ ref={(el) => {
+ attachReveal(el);
+ copyRef(el);
+ }}
className={cn(
"group relative overflow-hidden rounded-lg",
flash && "ring-2 ring-[#0a84ff] ring-offset-1"
diff --git a/site/src/cut/components/TemplateCard.tsx b/site/src/cut/components/TemplateCard.tsx
index f28b0646..93d3e9ce 100644
--- a/site/src/cut/components/TemplateCard.tsx
+++ b/site/src/cut/components/TemplateCard.tsx
@@ -29,7 +29,8 @@ import {
type TemplateDrag,
} from "@/cut/lib/assetDrag";
import { MEDIA_CORS } from "@/cut/lib/mediaCors";
-import { useAssetDrop, type AssetRef } from "@/cut/lib/assetRef";
+import { refFromTemplate, useAssetDrop, type AssetRef } from "@/cut/lib/assetRef";
+import { useRefCopy } from "@/cut/lib/refCopy";
import { cardIconButton } from "@/cut/components/iconButton";
import { formatTime } from "@/cut/lib/time";
import { EFFECT_LABELS } from "@donkeycut/effects-kit";
@@ -84,6 +85,9 @@ export function TemplateCard({
selected?: boolean;
}) {
const refDrop = useAssetDrop((r) => onRefDrop?.(r));
+ // ⌘C over the card copies its mention token, so a saved arrangement can be
+ // named in a prompt the same way a clip or an effect is.
+ const copyRef = useRefCopy(() => [refFromTemplate(t)]);
const [renaming, setRenaming] = useState(false);
const [draft, setDraft] = useState("");
const [expanded, setExpanded] = useState(false);
@@ -145,7 +149,10 @@ export function TemplateCard({
return (
<div
- ref={onRefDrop ? refDrop.attachTarget : undefined}
+ ref={(el) => {
+ if (onRefDrop) refDrop.attachTarget(el);
+ copyRef(el);
+ }}
{...(onRefDrop ? refDrop.targetProps : {})}
data-sel-id={selectId}
className={cn(
diff --git a/site/src/cut/components/entityIcons.ts b/site/src/cut/components/entityIcons.ts
index f0f321cb..c467fa7a 100644
--- a/site/src/cut/components/entityIcons.ts
+++ b/site/src/cut/components/entityIcons.ts
@@ -18,6 +18,7 @@ import {
FoldHorizontal,
Heart,
Hexagon,
+ Layers,
Minus,
Moon,
MoveRight,
@@ -105,6 +106,8 @@ export function entityIcon(ref: AssetRef): LucideIcon | null {
return Captions;
case "keyframe":
return Diamond;
+ case "template":
+ return Layers;
default:
return null;
}
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 652041e9..4db5b76f 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -55,6 +55,7 @@ import { applyOwnership, useGenerate, type VideoAttempt, type VideoGenOptions }
import { useGenScene } from "./genScene";
import { anchorRefused } from "./genvideo/shotAttempts";
import {
+ addProjectTemplateToTimeline,
addTemplateToProject,
createLibraryFolder,
deleteFromLibrary,
@@ -2583,12 +2584,18 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
template_add: async (s, input) => {
const projectId = s.projectId;
if (!projectId) throw new ToolError("No project open.");
- const t = (await fetchLibrary()).templates.find((x) => x.id === String(input.id ?? ""));
+ const id = String(input.id ?? "");
+ // A template saved into this project's own Media is already here, media
+ // and all; a Library one has to be carried in first.
+ const own = useEditor.getState().templates.find((x) => x.id === id);
+ const shelved = own ? null : (await fetchLibrary()).templates.find((x) => x.id === id);
+ const t = own ?? shelved;
if (!t)
- throw new ToolError(`No template with id ${String(input.id)}. Call library_list for ids.`);
+ throw new ToolError(`No template with id ${id}. Call library_list for ids.`);
const chatId = chatOwner();
const before = new Set(s.assets.map((a) => a.id));
- await addTemplateToProject(projectId, t);
+ if (shelved) await addTemplateToProject(projectId, shelved);
+ else addProjectTemplateToTimeline(projectId, t);
// Chat-fetched media files under the asking thread, like stock/library
// imports; the template's clips reference it, so it survives cleanup.
for (const a of useEditor.getState().assets) {
diff --git a/site/src/cut/lib/assetRef.ts b/site/src/cut/lib/assetRef.ts
index 1c9e4259..384fa57b 100644
--- a/site/src/cut/lib/assetRef.ts
+++ b/site/src/cut/lib/assetRef.ts
@@ -2,11 +2,18 @@
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import type React from "react";
-import { fetchLibrary, libraryRouteUrl, type LibraryAsset } from "./library";
+import { libraryRouteUrl, type LibraryAsset, type LibraryData } from "./library";
+import { useLibrary } from "./queries";
import { stockAspectDims, stockTitle, type StockImage, type StockMusic, type StockVideo } from "./stock";
import { STOCK_IMAGES } from "./stockManifest";
+import { STOCK_MUSIC } from "./stockMusicManifest";
import { STOCK_VIDEOS } from "./stockVideoManifest";
-import { EFFECT_LABELS, type EffectId } from "@donkeycut/effects-kit";
+import {
+ ALL_EFFECT_IDS,
+ EFFECT_LABELS,
+ isAudioEffect,
+ type EffectId,
+} from "@donkeycut/effects-kit";
import { clipLen, getClipSpans, useEditor } from "./store";
import {
isEffectOverlay,
@@ -14,6 +21,7 @@ import {
isStickerOverlay,
isTextOverlay,
SHAPE_LABELS,
+ TRANSITION_STYLE_IDS,
TRANSITION_STYLE_LABELS,
type ShapeKind,
type TransitionStyle,
@@ -85,8 +93,18 @@ export interface AssetRef {
* media order by `useRefCandidates`. Derived per session, not persisted —
* display surfaces re-resolve it live so a stale copy never shows. */
handle?: string;
- /** Which timeline entity an `"entity"` ref names — picks the pill's icon. */
- entityKind?: "title" | "shape" | "sticker" | "effect" | "transition" | "cue" | "keyframe";
+ /** Which timeline entity an `"entity"` ref names — picks the pill's icon.
+ * Catalog refs ride the same field: an effect, transition, shape or
+ * template a panel offers, waiting to be placed. */
+ entityKind?:
+ | "title"
+ | "shape"
+ | "sticker"
+ | "effect"
+ | "transition"
+ | "cue"
+ | "keyframe"
+ | "template";
/** The shape element's kind, for the pill's per-shape icon. */
shapeKind?: ShapeKind;
/** The transition bar's style, so its pill wears the icon its bar wears. */
@@ -419,8 +437,7 @@ export function useAssetDrop(
// ---------------------------------------------------------------------------
// Candidates and @name mentions
-let libraryCache: LibraryAsset[] | null = null;
-let libraryLoad: Promise<LibraryAsset[]> | null = null;
+const EMPTY_LIBRARY: LibraryData = { assets: [], folders: [], templates: [] };
/** The open project's media as refs with their session handles, assigned in
* media order — `v1` videos, `i1` generated stills, `a1` audio — so a prompt
@@ -695,6 +712,101 @@ export function entityRefs(src: EntitySources): AssetRef[] {
return out;
}
+/** Catalog ids live apart from timeline entity ids (`overlay:…`,
+ * `transition:…`); those name something the doc already holds. */
+export const CATALOG_PREFIX = "catalog:";
+
+/** Whether a ref names a panel catalog entry: a treatment waiting to be
+ * placed, offered by a panel and held nowhere in the cut yet. */
+export const isCatalogRef = (ref: AssetRef) =>
+ ref.scope === "entity" && ref.id.startsWith(CATALOG_PREFIX);
+
+/** The panels' catalogs as refs: every effect treatment, every transition
+ * style, every shape kind. Each names a thing that can be made, so a tile
+ * copied out of the Effects, Transitions or Elements tab pastes into a prompt
+ * as a grounded mention ("put a @\"Cross
+ * fade transition\" on that cut"). The payload carries the catalog id and the
+ * tool that places it, so the model acts on the exact treatment the user
+ * pointed at.
+ *
+ * Names carry the kind word ("Zoom effect", "Rectangle shape") so a catalog
+ * entry never collides with a timeline element wearing the same label; the
+ * live element keeps the bare name. */
+let catalogCache: AssetRef[] | null = null;
+
+export function catalogRefs(): AssetRef[] {
+ if (catalogCache) return catalogCache;
+ const out: AssetRef[] = [];
+ for (const id of ALL_EFFECT_IDS) {
+ const label = EFFECT_LABELS[id];
+ const audio = isAudioEffect(id);
+ out.push(
+ entityRef(
+ `${CATALOG_PREFIX}effect:${id}`,
+ `${label} ${audio ? "sound effect" : "effect"}`,
+ `the "${label}" ${audio ? "sound treatment" : "picture effect"} from the Effects tab, effect id "${id}". ` +
+ `Nothing on the timeline holds it yet. Place one with add_effect(effect: "${id}").`,
+ { entityKind: "effect", effectId: id }
+ )
+ );
+ }
+ for (const style of TRANSITION_STYLE_IDS) {
+ const label = TRANSITION_STYLE_LABELS[style];
+ out.push(
+ entityRef(
+ `${CATALOG_PREFIX}transition:${style}`,
+ `${label} transition`,
+ `the "${label}" transition from the Transitions tab, style id "${style}". ` +
+ `Nothing on the timeline holds it yet. Put one on a cut with set_transition(clipId, seconds, style: "${style}").`,
+ { entityKind: "transition", transitionStyle: style }
+ )
+ );
+ }
+ for (const shape of Object.keys(SHAPE_LABELS) as ShapeKind[]) {
+ const label = SHAPE_LABELS[shape];
+ out.push(
+ entityRef(
+ `${CATALOG_PREFIX}shape:${shape}`,
+ `${label} shape`,
+ `the "${label}" shape from the Elements tab, shape kind "${shape}". ` +
+ `Nothing on the timeline holds it yet. Place one with add_shape(shape: "${shape}").`,
+ { entityKind: "shape", shapeKind: shape }
+ )
+ );
+ }
+ // The catalogs are compile-time constants, so this is built once.
+ catalogCache = out;
+ return out;
+}
+
+/** One catalog entry by the id a panel tile already marks itself with
+ * (`effect:zoom`, `transition:crossfade`, `shape:rect`) — how ⌘C on a tile
+ * finds what that tile stands for. */
+export function catalogRefForPick(pickId: string): AssetRef | null {
+ return catalogRefs().find((r) => r.id === `${CATALOG_PREFIX}${pickId}`) ?? null;
+}
+
+/** A saved template as a ref — one on the shared shelf or one kept in this
+ * project's own Media. Like the panel catalogs it names a thing waiting to be
+ * placed, and its payload carries the id `template_add` takes, so "lay in
+ * @\"Intro template\"" reaches the right arrangement. */
+export function refFromTemplate(t: {
+ id: string;
+ name: string;
+ duration: number;
+ media: unknown[];
+}): AssetRef {
+ return entityRef(
+ `${CATALOG_PREFIX}template:${t.id}`,
+ `${t.name} template`,
+ `the "${t.name}" template — a saved arrangement of clips, titles and captions, ` +
+ `${t.duration.toFixed(1)}s long over ${t.media.length} media item${t.media.length === 1 ? "" : "s"}, ` +
+ `template id "${t.id}". Nothing on the timeline holds it yet. ` +
+ `Lay it into the cut with template_add(id: "${t.id}").`,
+ { entityKind: "template" }
+ );
+}
+
/** The prompt tokens for the current timeline selection, ready for the
* system clipboard — a picked keyframe first, then every selected clip,
* sound, element, transition, or cue that resolves to a ref. ⌘C writes this
@@ -744,7 +856,9 @@ export function selectionRefTokens(s: EntitySources & {
* clips first — video-track clips, then soundtrack clips (what's in front of
* the user — a bare `@` leads with the cut), then the timeline's media-less
* entities (elements, transitions, cues, keyframes — pasted in via ⌘C), then
- * the open project's media, the shared library, and the stock catalog.
+ * the open project's media and its saved templates, the shared library, the
+ * stock catalog, and last the panels' own catalogs of effects, transitions and
+ * shapes.
* Names are unique within the list (first scope wins) so a mention resolves
* to one asset. Library items mention by name; stock ids are already short
* (`@nature-dunes`). */
@@ -755,18 +869,11 @@ export function useRefCandidates(): AssetRef[] {
const overlays = useEditor((s) => s.overlays);
const transitions = useEditor((s) => s.transitions);
const subtitles = useEditor((s) => s.subtitles);
- const [lib, setLib] = useState<LibraryAsset[]>(libraryCache ?? []);
-
- useEffect(() => {
- libraryLoad ??= fetchLibrary()
- .then((d) => (libraryCache = d.assets))
- .catch(() => (libraryCache = []));
- let alive = true;
- void libraryLoad.then((l) => alive && setLib(l));
- return () => {
- alive = false;
- };
- }, []);
+ const projectTemplates = useEditor((s) => s.templates);
+ // The same listing the Library panel and the Camera Roll read, so a clip
+ // uploaded from the phone or a template just pushed to the shelf is
+ // mentionable the moment it lands.
+ const lib = useLibrary().data ?? EMPTY_LIBRARY;
return useMemo(() => {
const project = projectRefs(assets);
@@ -777,9 +884,15 @@ export function useRefCandidates(): AssetRef[] {
...audioClipRefs(audioClips, assets),
...entityRefs({ clips, assets, overlays, transitions, subtitles }),
...project,
- ...lib.map(refFromLibrary),
+ ...projectTemplates.map(refFromTemplate),
+ // A font is used from the font menu, so there is nothing to point a tool
+ // at; library fonts stay out of the candidates the way project fonts do.
+ ...lib.assets.filter((a) => a.type !== "font").map(refFromLibrary),
+ ...lib.templates.map(refFromTemplate),
...STOCK_IMAGES.map(refFromStock),
...STOCK_VIDEOS.map(refFromStockVideo),
+ ...STOCK_MUSIC.map(refFromStockMusic),
+ ...catalogRefs(),
]) {
const key = ref.name.toLowerCase();
if (seen.has(key)) continue;
@@ -787,7 +900,7 @@ export function useRefCandidates(): AssetRef[] {
out.push(ref);
}
return out;
- }, [assets, clips, audioClips, overlays, transitions, subtitles, lib]);
+ }, [assets, clips, audioClips, overlays, transitions, subtitles, projectTemplates, lib]);
}
/** The prompt token for an asset name: `@name`, quoted when it has spaces. */
diff --git a/site/src/cut/lib/refCopy.ts b/site/src/cut/lib/refCopy.ts
new file mode 100644
index 00000000..94787af0
--- /dev/null
+++ b/site/src/cut/lib/refCopy.ts
@@ -0,0 +1,221 @@
+"use client";
+
+/**
+ * ⌘C on anything referenceable, everywhere in the app.
+ *
+ * A card, a tile or a chat asset registers what it stands for as an
+ * {@link AssetRef}; ⌘C writes that ref's mention token to the system clipboard,
+ * and pasting it into any prompt — the chat composer, the image and video
+ * creators — brings the thing itself along, because the composer resolves
+ * mention tokens back to refs on send (`collectRefs`).
+ *
+ * One registry serves every surface. Sources register through
+ * {@link useRefCopy}; panel tiles that already mark themselves with
+ * `data-pick-id` (effects, transitions, shapes, generated stills) are resolved
+ * straight off that attribute, so those grids need no wiring of their own.
+ *
+ * What a ⌘C copies is what the pointer is on, falling back to what has focus —
+ * the cursor is the deliberate pick, and a tile clicked a moment ago keeps
+ * focus long after the pointer has moved on.
+ */
+
+import { useCallback, useEffect, useRef } from "react";
+
+import {
+ catalogRefForPick,
+ projectRefs,
+ refFromAsset,
+ refToken,
+ type AssetRef,
+} from "./assetRef";
+import { useEditor } from "./store";
+
+type RefsFn = () => AssetRef[];
+
+interface CopySource {
+ el: HTMLElement;
+ refs: RefsFn;
+}
+
+/** The registry lives on the window. A hot reload re-evaluates this module,
+ * and a module-scoped Set would leave the already-installed listener reading an
+ * empty registry while fresh cards register into a Set nothing listens to. */
+interface Registry {
+ sources: Set<CopySource>;
+ /** Where the pointer last was, so a ⌘C copies what the cursor is on. */
+ x: number;
+ y: number;
+ installed: boolean;
+}
+
+const registry: Registry = ((globalThis as unknown as { __cutRefCopy?: Registry })
+ .__cutRefCopy ??= { sources: new Set<CopySource>(), x: -1, y: -1, installed: false });
+
+const sources = registry.sources;
+
+/** The innermost registered source holding `node`. */
+function sourceFor(node: Node | null): CopySource | null {
+ if (!node) return null;
+ let best: CopySource | null = null;
+ for (const s of sources) {
+ if (!s.el.contains(node)) continue;
+ // A card inside a grid that also registers wins: the smaller box is the
+ // more specific answer.
+ if (!best || best.el.contains(s.el)) best = s;
+ }
+ return best;
+}
+
+/** A panel tile's pick id resolves without registration: the catalogs
+ * (`effect:zoom`, `transition:crossfade`, `shape:rect`) and the generated
+ * stills and stickers, whose pick id is their project asset id. */
+function refForPickId(pickId: string): AssetRef | null {
+ const catalog = catalogRefForPick(pickId);
+ if (catalog) return catalog;
+ const asset = useEditor.getState().assets.find((a) => a.id === pickId);
+ return asset ? refFromAsset(asset) : null;
+}
+
+/** What a ⌘C at `node` names, registration first, then the pick id the tile
+ * already carries. */
+function refsAt(node: Node | null): AssetRef[] {
+ const registered = sourceFor(node);
+ if (registered) return registered.refs();
+ const tile = (node instanceof Element ? node : node?.parentElement)?.closest?.(
+ "[data-pick-id]"
+ );
+ const pickId = tile instanceof HTMLElement ? tile.dataset.pickId : null;
+ const ref = pickId ? refForPickId(pickId) : null;
+ return ref ? [ref] : [];
+}
+
+/** Short handles (`v2`, `i1`) are derived per session and never stored, so the
+ * keystroke resolves them against the live asset list. */
+function withHandle(ref: AssetRef): AssetRef {
+ if (ref.scope !== "project") return ref;
+ const live = projectRefs(useEditor.getState().assets).find((r) => r.id === ref.id);
+ return live?.handle ? { ...ref, handle: live.handle } : ref;
+}
+
+/** Whether the keyboard is in a text field, where ⌘C means the native copy. */
+function inTextField(): boolean {
+ const el = document.activeElement;
+ if (!(el instanceof HTMLElement)) return false;
+ return (
+ el instanceof HTMLInputElement ||
+ el instanceof HTMLTextAreaElement ||
+ el.isContentEditable
+ );
+}
+
+/** The input types that carry a text range; the rest report none. */
+const SELECTABLE_INPUT = new Set(["text", "search", "url", "tel", "password"]);
+
+/** Whether the user has text picked out, which makes a ⌘C mean copy that text.
+ * `window.getSelection()` covers the page and contenteditable; a range inside
+ * an input or a textarea shows up only on the field itself, so a highlighted
+ * sentence in the chat composer reads as empty there and has to be asked for
+ * directly. */
+function hasTextSelection(): boolean {
+ if (window.getSelection()?.toString()) return true;
+ const el = document.activeElement;
+ const field =
+ el instanceof HTMLTextAreaElement ||
+ (el instanceof HTMLInputElement && SELECTABLE_INPUT.has(el.type));
+ if (!field) return false;
+ const { selectionStart: from, selectionEnd: to } = el;
+ return from !== null && to !== null && to > from;
+}
+
+/**
+ * The refs a ⌘C right now would copy — empty when the pointer and the focus
+ * are both off any referenceable thing. The editor's own ⌘C reads this to know
+ * when to stand aside and let the copy land on the card under the cursor
+ * instead of the timeline selection.
+ *
+ * Text the user has picked out owns the keystroke. Failing that the pointer
+ * answers: a card under the cursor is the deliberate pick even while the caret
+ * sits in the chat composer. Focus answers last — a tile clicked a moment ago
+ * keeps focus long after the pointer has moved on — and a text field with the
+ * caret in it keeps the native copy.
+ */
+export function copyableRefs(): AssetRef[] {
+ // Text the user picked out owns the keystroke, wherever it was picked.
+ if (hasTextSelection()) return [];
+ const under = registry.x >= 0 ? document.elementFromPoint(registry.x, registry.y) : null;
+ const hovered = refsAt(under);
+ if (hovered.length > 0) return hovered.map(withHandle);
+ if (inTextField()) return [];
+ return refsAt(document.activeElement).map(withHandle);
+}
+
+/** The clipboard text for a set of refs: their mention tokens, space-joined. */
+export const refClipboardText = (refs: AssetRef[]) => refs.map(refToken).join(" ");
+
+/**
+ * Put refs on the system clipboard. The tile's own copy buttons and the ⌘C
+ * path both land here, so what a click copies and what the keystroke copies
+ * are the same string.
+ */
+export function copyRefs(refs: AssetRef[]): boolean {
+ if (refs.length === 0) return false;
+ void navigator.clipboard?.writeText(refClipboardText(refs.map(withHandle))).catch(() => {});
+ return true;
+}
+
+// ---------------------------------------------------------------------------
+// The one listener
+
+function install() {
+ if (typeof document === "undefined") return;
+ if (registry.installed) return;
+ registry.installed = true;
+ window.addEventListener(
+ "pointermove",
+ (e) => {
+ registry.x = e.clientX;
+ registry.y = e.clientY;
+ },
+ { capture: true, passive: true }
+ );
+ // A `copy` event fires only where the browser sees something to copy, so the
+ // keystroke is what a bare card under the cursor answers to. Bubbling on the
+ // document puts this ahead of the editor's own window-level ⌘C, which reads
+ // `copyableRefs` and stands aside when a card answers.
+ document.addEventListener("keydown", (e) => {
+ if (!(e.metaKey || e.ctrlKey) || e.altKey || e.key.toLowerCase() !== "c") return;
+ const refs = copyableRefs();
+ if (refs.length === 0) return;
+ e.preventDefault();
+ copyRefs(refs);
+ });
+}
+
+// The keystroke reaches surfaces that register nothing of their own — a panel
+// of effect tiles resolved off `data-pick-id` — so the listener goes on with
+// the module rather than with the first source.
+install();
+
+/**
+ * Register an element as what a ⌘C over it copies. `refs` is read at the
+ * keystroke, so a card can answer with the whole selection it belongs to.
+ *
+ * const copyRef = useRefCopy(() => [refFromLibrary(asset)]);
+ * <div ref={copyRef}>…</div>
+ */
+export function useRefCopy(refs: RefsFn): (el: HTMLElement | null) => void {
+ const latest = useRef(refs);
+ useEffect(() => {
+ latest.current = refs;
+ });
+ const source = useRef<CopySource | null>(null);
+ return useCallback((el: HTMLElement | null) => {
+ if (source.current) {
+ sources.delete(source.current);
+ source.current = null;
+ }
+ if (!el) return;
+ source.current = { el, refs: () => latest.current() };
+ sources.add(source.current);
+ }, []);
+}
diff --git a/site/src/cut/lib/refMedia.ts b/site/src/cut/lib/refMedia.ts
index aef039cb..be1847fd 100644
--- a/site/src/cut/lib/refMedia.ts
+++ b/site/src/cut/lib/refMedia.ts
@@ -1,6 +1,6 @@
"use client";
-import { refFromAsset, refFromTextFile, type AssetRef } from "./assetRef";
+import { isCatalogRef, refFromAsset, refFromTextFile, type AssetRef } from "./assetRef";
import { tagChatAsset } from "./chatAssets";
import { startUpload } from "./importQueue";
import {
@@ -412,9 +412,11 @@ export async function refsToParts(
if (ref.kind === "text") {
parts.push({
text:
- ref.scope === "entity"
- ? `Referenced timeline entity "${ref.name}":\n${await readRefText(ref)}`
- : `Attached file "${ref.name}":\n${await readRefText(ref)}`,
+ isCatalogRef(ref)
+ ? `Referenced "${ref.name}" — ${await readRefText(ref)}`
+ : ref.scope === "entity"
+ ? `Referenced timeline entity "${ref.name}":\n${await readRefText(ref)}`
+ : `Attached file "${ref.name}":\n${await readRefText(ref)}`,
});
continue;
}