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.mdindex 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 livesdiff --git a/site/src/cut/components/ChatAssets.tsx b/site/src/cut/components/ChatAssets.tsxindex 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.tsxindex 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 stepsdiff --git a/site/src/cut/components/GeneratePanel.tsx b/site/src/cut/components/GeneratePanel.tsxindex 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 (<divref={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.tsxindex 667cdd70..17d07beb 100644--- a/site/src/cut/components/ImageGenPanel.tsx+++ b/site/src/cut/components/ImageGenPanel.tsx@@ -243,6 +243,7 @@ function GeneratedTile({return (<divref={tileRef}+ data-pick-id={asset.id}className={cn("group relative overflow-hidden rounded-lg", picked && PICKED_RING)}><buttondiff --git a/site/src/cut/components/LibraryView.tools.ts b/site/src/cut/components/LibraryView.tools.tsindex 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.tsxindex 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({<CopyNameLabelname={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.tsxindex 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 }) {mentionselected={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.tsxindex 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.tsxindex 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"draggableonDragStart={(e) => {diff --git a/site/src/cut/components/StockVideosPanel.tsx b/site/src/cut/components/StockVideosPanel.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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;}