Open source CapCut alternative.
TypeScript
feat(site): give each timeline its own aspect ratio, starting from Main's [rebuild]
David Le359eb1908bc0
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.mdindex 96a5a9ef..4b0446a1 100644--- a/docs/guides/cut/README.md+++ b/docs/guides/cut/README.md@@ -46,7 +46,7 @@ Browser previews use the browser compositor and replace one cached proxy in OPFSCloud source media, generated media, and retained exports count toward storage. Derived previews, share cards, and HLS ladders are quota-exempt; staging inputs are temporary. An export is weighed twice — the size it is heading for before a frame is drawn, and what actually landed before the account is charged — so one render cannot carry an account past its cap. Transports expose structured storage, credit, and authentication failures. Each host chooses their presentation; the website mounts its storage dialog separately.-A project has three timelines, Main, Second and Third, picked from the timeline toolbar; a share link plays the one its settings pick, Main by default.+A project has three timelines, Main, Second and Third, each with its own frame; a share link plays the one its settings pick.Timeline and preview share selection: ⌘/Ctrl-click or Shift-click toggles items; dragging moves them with one undo step. Groups persist. Their preview frame scales and rotates the selection; the group panel edits shared fields, showing Mixed where values differ. Text side grips change wrapping width and corners scale proportionally; height follows content across preview, export and chat.diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.tsindex 139ffec3..3cdd2d12 100644--- a/site/src/cut/components/Timeline.tools.ts+++ b/site/src/cut/components/Timeline.tools.ts@@ -370,7 +370,7 @@ export const TIMELINE_TOOLS = [},{name: "switch_timeline",- description: `Open another of the project's ${TIMELINE_IDS.length} timelines (${TIMELINE_IDS.map((id) => `${id} = ${TIMELINE_LABELS[id]}`).join(", ")}) — the picker at the left of the timeline toolbar. Each timeline holds its own clips, soundtrack, transitions, elements and subtitles; the media, the frame and the project settings are shared. The preview, the export and every other tool work on the open one, which editor_state project.timeline names, with project.timelines summarizing each. A timeline opened for the first time is empty, and each keeps its own undo history. A share link plays the timeline its share settings pick, Main by default. There are exactly these ${TIMELINE_IDS.length}; none can be added, renamed or deleted.`,+ description: `Open another of the project's ${TIMELINE_IDS.length} timelines (${TIMELINE_IDS.map((id) => `${id} = ${TIMELINE_LABELS[id]}`).join(", ")}) — the picker at the left of the timeline toolbar. Each timeline holds its own clips, soundtrack, transitions, elements, subtitles and aspect ratio; the media and the project settings are shared. The preview, the export and every other tool work on the open one, which editor_state project.timeline names, with project.timelines summarizing each. A timeline opened for the first time is empty at Main's aspect ratio, and each keeps its own undo history. A share link plays the timeline its share settings pick, Main by default. There are exactly these ${TIMELINE_IDS.length}; none can be added, renamed or deleted.`,inputSchema: obj({timeline: { type: "string", enum: [...TIMELINE_IDS], description: "The timeline to open" },}, ["timeline"]),diff --git a/site/src/cut/components/TopBar.tools.ts b/site/src/cut/components/TopBar.tools.tsindex 6a873415..16390764 100644--- a/site/src/cut/components/TopBar.tools.ts+++ b/site/src/cut/components/TopBar.tools.ts@@ -14,7 +14,7 @@ export const TOP_BAR_TOOLS = [{name: "set_aspect",description:- "Set the project's output frame ratio as \"W:H\". The frame is the user's own setting, so call this only when they asked for a shape or a format (\"make it vertical\", \"for TikTok\", \"square\") — never inferred from a reference image's shape, a platform named in passing, or what would suit a generation you are about to run. Presets: 16:9 (YouTube), 9:16 (TikTok/Reels/Shorts), 1:1, 4:3, 3:4, 2:1 — but any ratio up to an 8:1 shape works, with whole or decimal sides (\"9:5\", \"2.39:1\" — stored reduced, so 2.39:1 becomes 239:100). The frame renders with its short side at 1080px: 9:16 → 1080×1920, 16:9 → 1920×1080, 9:5 → 1944×1080.",+ "Set the open timeline's output frame ratio as \"W:H\"; each timeline keeps its own. The frame is the user's own setting, so call this only when they asked for a shape or a format (\"make it vertical\", \"for TikTok\", \"square\") — never inferred from a reference image's shape, a platform named in passing, or what would suit a generation you are about to run. Presets: 16:9 (YouTube), 9:16 (TikTok/Reels/Shorts), 1:1, 4:3, 3:4, 2:1 — but any ratio up to an 8:1 shape works, with whole or decimal sides (\"9:5\", \"2.39:1\" — stored reduced, so 2.39:1 becomes 239:100). The frame renders with its short side at 1080px: 9:16 → 1080×1920, 16:9 → 1920×1080, 9:5 → 1944×1080.",inputSchema: obj({ aspect: { type: "string", description: "Output ratio as \"W:H\", e.g. \"9:16\", \"1:1\", \"9:5\", \"2.39:1\"" } }, ["aspect"]),},{diff --git a/site/src/cut/lib/aiContext.ts b/site/src/cut/lib/aiContext.tsindex 317adffe..f4726ba6 100644--- a/site/src/cut/lib/aiContext.ts+++ b/site/src/cut/lib/aiContext.ts@@ -1,7 +1,7 @@"use client";import { formatBytes } from "@/lib/bytes";-import { isLinkedAssetType, isTimelineId, sanitizeTimelines, TIMELINE_IDS, TIMELINE_LABELS, type TimelineBody, type TimelineId } from "./types";+import { isLinkedAssetType, isTimelineId, sanitizeTimelines, timelineAspect, TIMELINE_IDS, TIMELINE_LABELS, type TimelineBody, type TimelineId } from "./types";import { GUIDE_PRESETS, guideFits, guideGeometry, safeAreaOf, sanitizeGuideLines, sanitizeGuides, type GuideId, type GuideLines } from "./guides";import { hasOverlayAnim, retimeOf, speedCurveOf, WHEEL_LABELS, WHEEL_ZONES, type ClipSound, type OutputSpace, type SpeedNode } from "@donkeycut/effects-kit";import { chatOwner } from "./chatAssets";@@ -286,6 +286,7 @@ export function buildAiContext(opts?: { fullCues?: boolean; chatId?: string | nuexport function describeDoc(doc: ProjectDoc, opts?: { fullCues?: boolean; chatId?: string | null }) {const assets: MediaAsset[] = (doc.assets ?? []).map((a) => ({ ...a, url: "" }));const state = normalizeDocState(doc, assets);+ const aspect = state.aspect ?? "9:16";const core = describeState({projectId: doc.id ?? null,@@ -300,7 +301,7 @@ export function describeDoc(doc: ProjectDoc, opts?: { fullCues?: boolean; chatIdsubtitles: state.subtitles,subtitleLane: 0,subtitleStatus: state.subtitles.cues.length > 0 ? "ready" : "idle",- aspect: state.aspect ?? "9:16",+ aspect,background: state.background,colorSpace: state.colorSpace,guides: sanitizeGuides(doc.guides),@@ -308,7 +309,7 @@ export function describeDoc(doc: ProjectDoc, opts?: { fullCues?: boolean; chatIdgenvideo: doc.genvideo ?? undefined,mediaFolders: doc.mediaFolders ?? [],timeline: isTimelineId(doc.timeline) ? doc.timeline : "main",- timelines: sanitizeTimelines(doc.timelines) ?? {},+ timelines: sanitizeTimelines(doc.timelines, { aspect }) ?? {},},{ fullCues: opts?.fullCues === true, chatId: opts?.chatId ?? null, live: false });@@ -406,6 +407,7 @@ function describeState(...(id === s.timeline ? { open: true } : {}),duration: r(body ? projectDuration(body) : 0),clips: body?.clips.length ?? 0,+ aspect: timelineAspect(s, id),};}),aspect: s.aspect,diff --git a/site/src/cut/lib/backend/browser/router.ts b/site/src/cut/lib/backend/browser/router.tsindex f8cf78e5..a66f363a 100644--- a/site/src/cut/lib/backend/browser/router.ts+++ b/site/src/cut/lib/backend/browser/router.ts@@ -93,7 +93,7 @@ async function putProject(req: Request, id: string): Promise<Response> {: existing.overlayClips,overlays: Array.isArray(body.overlays) ? body.overlays : existing.overlays,timeline: isTimelineId(body.timeline) ? body.timeline : existing.timeline,- timelines: sanitizeTimelines(body.timelines) ?? existing.timelines,+ timelines: sanitizeTimelines(body.timelines, existing) ?? existing.timelines,templates: Array.isArray(body.templates) ? body.templates : existing.templates,mediaFolders: Array.isArray(body.mediaFolders) ? body.mediaFolders : existing.mediaFolders,aspect: normalizeAspect(body.aspect) ?? existing.aspect,diff --git a/site/src/cut/lib/engineFeatures.ts b/site/src/cut/lib/engineFeatures.tsindex 034e25ac..ef02d07a 100644--- a/site/src/cut/lib/engineFeatures.ts+++ b/site/src/cut/lib/engineFeatures.ts@@ -4,6 +4,6 @@* hands an engine work an older app would silently drop. A build from before* the list existed answers with none.*/-export const ENGINE_FEATURES = ["export.range", "export.name", "export.prores4444", "color.v2", "media.proxy", "export.hdr", "doc.timelines"] as const;+export const ENGINE_FEATURES = ["export.range", "export.name", "export.prores4444", "color.v2", "media.proxy", "export.hdr", "doc.timelines", "doc.timelineAspect"] as const;export type EngineFeature = (typeof ENGINE_FEATURES)[number];diff --git a/site/src/cut/lib/exportClient.ts b/site/src/cut/lib/exportClient.tsindex 5bfc76a7..34dcabd6 100644--- a/site/src/cut/lib/exportClient.ts+++ b/site/src/cut/lib/exportClient.ts@@ -30,7 +30,7 @@ import { clipLen, clipSpeed, getClipSpans, openedTimeline, overlayLayers, projecimport { captionStyle, cueOverlay, cueWordFrames, laneCues, laneHidden, subtitleLaneCount, trackPos } from "./subtitles";import { isMaskAnimated, isOverlayAnimated, matteLumaToAlpha, normalizeGrade, paintMaskLuma, paintStrokeInk, retimeOf, type SpeedNode } from "@donkeycut/effects-kit";import { renderElementFrames, renderElementPng } from "./textRender";-import { clipCovers, clipKeyed, clipPosed, clipPoseAt, clipZoom, contentRect, frameOf, isStickerOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, rectOf, regionPx, removalActive, shadowInk, subjectMasked } from "./types";+import { clipCovers, clipKeyed, clipPosed, clipPoseAt, clipZoom, contentRect, frameOf, isStickerOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, rectOf, regionPx, removalActive, shadowInk, subjectMasked, parkedTimeline } from "./types";import { liveReader } from "./liveReader";import type {Aspect,@@ -2156,7 +2156,8 @@ function sharedCut(doc: ExportDoc, timeline: TimelineId | undefined): { cut: Expconst { timeline: open = "main", timelines, ...cut } = doc;const want = timeline ?? "main";if (want === open) return { cut, key: null };- const parked = { ...cut, ...openedTimeline(timelines?.[want] ?? {}, doc.assets) };+ const { aspect, ...body } = parkedTimeline({ aspect: cut.aspect, timeline: open, timelines: timelines ?? {} }, want);+ const parked = { ...cut, ...openedTimeline(body, doc.assets), aspect };return { cut: parked, key: shareRenderKey(parked) };}diff --git a/site/src/cut/lib/store.test.ts b/site/src/cut/lib/store.test.tsindex 93ded8dc..56ce58db 100644--- a/site/src/cut/lib/store.test.ts+++ b/site/src/cut/lib/store.test.ts@@ -275,6 +275,40 @@ describe("timelines", () => {expect(s().timelines.main?.clips).toEqual([]);});+ test("each timeline keeps its own aspect", () => {+ s().setAspect("16:9");+ s().switchTimeline("second");+ // Opened for the first time: Main's frame.+ expect(s().aspect).toBe("16:9");+ s().setAspect("9:16");+ s().switchTimeline("third");+ expect(s().aspect).toBe("16:9");+ s().switchTimeline("main");+ expect(s().aspect).toBe("16:9");+ expect(s().timelines.second?.aspect).toBe("9:16");+ const doc = serializeDoc(s() as Parameters<typeof serializeDoc>[0]);+ expect(sanitizeTimelines(doc.timelines)?.second?.aspect).toBe("9:16");+ s().switchTimeline("second");+ expect(s().aspect).toBe("9:16");+ });++ test("a timeline parked where the frame was project-wide keeps the doc's", () => {+ const body = { clips: [], audioClips: [], transitions: [], overlays: [], subtitles: emptySubtitles() };+ expect(sanitizeTimelines({ main: body }, { aspect: "16:9" })?.main?.aspect).toBe("16:9");+ // A save from such a client keeps the frame the doc already holds.+ const prior = { aspect: "9:16", timelines: { main: { ...body, aspect: "4:3" as const } } };+ expect(sanitizeTimelines({ main: body }, prior)?.main?.aspect).toBe("4:3");+ expect(sanitizeTimelines({ main: { ...body, aspect: "1:1" } }, prior)?.main?.aspect).toBe("1:1");+ });++ test("an engine without per-timeline frames keeps one frame across switches", () => {+ s().setAspect("16:9");+ s().switchTimeline("second", { ownAspect: false });+ s().setAspect("9:16");+ s().switchTimeline("main", { ownAspect: false });+ expect(s().aspect).toBe("9:16");+ });+test("a parked timeline missing a list reads it as empty", () => {const parked = sanitizeTimelines({ second: { clips: [] }, bogus: { clips: [] } });expect(parked).toEqual({diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.tsindex 450051ba..7659b0c8 100644--- a/site/src/cut/lib/store.ts+++ b/site/src/cut/lib/store.ts@@ -89,7 +89,7 @@ import { clampPlayhead, playheadAt, previewAt, setPlayhead, setSkim } from "./plimport { engineTranscribeSamples, withEngineStt } from "./localStt";import { laneCues, subtitleLaneCount, trackLocale } from "./subtitles";import { clipboardItemAssetIds, clipboardItemFor, listedAssetIds, type TimelineClipboardItem } from "./itemKinds";-import { ANIM_STYLE_IDS, animStyleOfTransition, assetIsSilent, clipPoseAt, DEFAULT_BACKGROUND, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isAudioTransition, fontAssetId, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, projectBackground, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, isTimelineId, sanitizeTimelines, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionBarAt, transitionBarStart, transitionStyleOfAnim, type TransitionBoundaryKind } from "./types";+import { ANIM_STYLE_IDS, animStyleOfTransition, assetIsSilent, clipPoseAt, DEFAULT_BACKGROUND, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isAudioTransition, fontAssetId, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, projectBackground, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, isTimelineId, sanitizeTimelines, timelineAspect, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionBarAt, transitionBarStart, transitionStyleOfAnim, type TransitionBoundaryKind } from "./types";import { liftMoveTracks } from "./textMotion";import { readTextStyle } from "./textStyle";import { loadUiState, saveUiState, type ProjectUiState } from "./uiState";@@ -437,15 +437,16 @@ export interface EditorState {transitions: TimelineTransition[];audioClips: AudioClip[];overlays: Overlay[];- /** The open timeline: clips, transitions, audio, elements and subtitles- * above are its content. */+ /** The open timeline: clips, transitions, audio, elements, subtitles and+ * aspect are its content. */timeline: TimelineId;/** The closed timelines' content, parked as the document stores it. */timelines: Partial<Record<TimelineId, TimelineBody>>;/** Park the open timeline and open another. Each timeline keeps its own- * undo history for the session. */- switchTimeline: (id: TimelineId) => void;- /** Output frame ratio ("W:H", short side 1080), persisted per project. */+ * undo history for the session, and its own frame where the storage keeps+ * one per timeline (`ownAspect`). */+ switchTimeline: (id: TimelineId, opts?: { ownAspect?: boolean }) => void;+ /** Output frame ratio ("W:H", short side 1080), persisted per timeline. */aspect: Aspect;/** The aspect was chosen deliberately (picker, set_aspect, or saved in the* doc) — the first-import orientation guess stands down. Not a doc field. */@@ -2183,6 +2184,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {applyDocState: (doc, assets, ui) => {const state = normalizeDocState(doc, assets);+ const aspect = state.aspect ?? lastChosenAspect() ?? "9:16";hydrating = true;try {set({@@ -2193,10 +2195,10 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {audioClips: state.audioClips,overlays: state.overlays,timeline: isTimelineId(doc.timeline) ? doc.timeline : "main",- timelines: sanitizeTimelines(doc.timelines) ?? {},+ timelines: sanitizeTimelines(doc.timelines, { aspect }) ?? {},templates: doc.templates ?? [],mediaFolders: doc.mediaFolders ?? [],- aspect: state.aspect ?? lastChosenAspect() ?? "9:16",+ aspect,aspectTouched: doc.aspect !== undefined || lastChosenAspect() !== null,guides: sanitizeGuides(doc.guides),guidesHidden: false,@@ -2471,7 +2473,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {}));},setBackground: (hex) => set({ background: projectBackground(hex) }),- switchTimeline: (id) => {+ switchTimeline: (id, opts) => {const s = get();if (id === s.timeline || s.readOnly || !isTimelineId(id)) return;const opened = normalizeDocState(s.timelines[id] ?? {}, s.assets);@@ -2481,6 +2483,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {transitions: s.transitions,overlays: docOverlays(s.overlays),subtitles: s.subtitles,+ aspect: s.aspect,};const rest = { ...s.timelines };delete rest[id];@@ -2506,6 +2509,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {audioClips: opened.audioClips,overlays: opened.overlays,subtitles: opened.subtitles,+ aspect: opts?.ownAspect === false ? s.aspect : timelineAspect(s, id),subtitleLane: 0,subtitleStatus: opened.subtitles.cues.length > 0 ? "ready" : "idle",subtitleError: null,diff --git a/site/src/cut/lib/timelineSwitch.ts b/site/src/cut/lib/timelineSwitch.tsindex 3cf4db33..a9540522 100644--- a/site/src/cut/lib/timelineSwitch.ts+++ b/site/src/cut/lib/timelineSwitch.ts@@ -6,15 +6,19 @@ import { useMatteBakes, type MatteBakeJob } from "./removal/bakeJobs";import { useEditor } from "./store";import { TIMELINE_LABELS, type TimelineId } from "./types";-/** Whether the open project's storage keeps more than one timeline. An engine- * from before timelines rebuilds the saved doc without the parked ones, so a- * Mac project on an older app stays on Main. A headless turn runs inside the- * same build that stores the doc. */-export async function timelinesSupported(): Promise<boolean> {- if (typeof window === "undefined" || getBackend().kind !== "local") return true;- return (await engineFeatures()).has("doc.timelines");+/** What the open project's storage keeps of its timelines. An engine from+ * before timelines rebuilds the saved doc without the parked ones, so a Mac+ * project on an older app stays on Main; one from before per-timeline frames+ * drops their aspect, so its timelines share one frame. A headless turn runs+ * inside the same build that stores the doc. */+async function timelineStorage(): Promise<{ timelines: boolean; aspects: boolean }> {+ if (typeof window === "undefined" || getBackend().kind !== "local") return { timelines: true, aspects: true };+ const features = await engineFeatures();+ return { timelines: features.has("doc.timelines"), aspects: features.has("doc.timelineAspect") };}+export const timelinesSupported = async () => (await timelineStorage()).timelines;+const baking = (jobs: Record<string, MatteBakeJob>) => Object.values(jobs).some((j) => j.status === "running");/** Why the open timeline cannot be left right now, or null when it can. Work@@ -33,10 +37,11 @@ export function timelineSwitchBlocker(): string | null {/** Open another of the project's timelines, or say why it cannot. */export async function switchTimeline(id: TimelineId): Promise<string | null> {- if (!(await timelinesSupported())) return "Update the Donkey app to use more than one timeline.";+ const storage = await timelineStorage();+ if (!storage.timelines) return "Update the Donkey app to use more than one timeline.";const blocked = timelineSwitchBlocker();if (blocked) return blocked;- useEditor.getState().switchTimeline(id);+ useEditor.getState().switchTimeline(id, { ownAspect: storage.aspects });return null;}diff --git a/site/src/cut/lib/types.ts b/site/src/cut/lib/types.tsindex 11714f3c..ca70bf75 100644--- a/site/src/cut/lib/types.ts+++ b/site/src/cut/lib/types.ts@@ -1601,11 +1601,46 @@ export interface TimelineBody {transitions: TimelineTransition[];overlays: Overlay[];subtitles: SubtitlesBlock;+ /** The timeline's frame; absent = it has not been opened yet and takes+ * Main's. */+ aspect?: Aspect;+}++/** A timeline's frame: the open one's is the doc's own, a parked one keeps+ * its own, and one never opened takes Main's. */+export function timelineAspect(+ doc: { aspect: Aspect; timeline: TimelineId; timelines: Partial<Record<TimelineId, Pick<TimelineBody, "aspect">>> },+ id: TimelineId+): Aspect {+ if (id === doc.timeline) return doc.aspect;+ return doc.timelines[id]?.aspect ?? (id === "main" ? doc.aspect : timelineAspect(doc, "main"));+}++/** A parked timeline as a cut of its own: its lists, empty when it was never+ * opened, and its frame. What a share link playing it draws. */+export function parkedTimeline(+ doc: { aspect: Aspect; timeline: TimelineId; timelines: Partial<Record<TimelineId, TimelineBody>> },+ id: TimelineId+): Required<TimelineBody> {+ const body = doc.timelines[id];+ return {+ clips: body?.clips ?? [],+ audioClips: body?.audioClips ?? [],+ transitions: body?.transitions ?? [],+ overlays: body?.overlays ?? [],+ subtitles: body?.subtitles ?? emptySubtitles(),+ aspect: timelineAspect(doc, id),+ };}/** The parked timelines a save sent, each with every list it carries: a- * missing or malformed one reads as empty. */-export function sanitizeTimelines(v: unknown): Partial<Record<TimelineId, TimelineBody>> | undefined {+ * missing or malformed one reads as empty. A body without its aspect was+ * written where the frame was project-wide, so it takes the one `prior` kept+ * for it, else the doc's. */+export function sanitizeTimelines(+ v: unknown,+ prior?: { aspect?: string; timelines?: Partial<Record<TimelineId, TimelineBody>> }+): Partial<Record<TimelineId, TimelineBody>> | undefined {if (!v || typeof v !== "object" || Array.isArray(v)) return undefined;const list = <T,>(x: unknown): T[] => (Array.isArray(x) ? (x as T[]) : []);const out: Partial<Record<TimelineId, TimelineBody>> = {};@@ -1613,6 +1648,10 @@ export function sanitizeTimelines(v: unknown): Partial<Record<TimelineId, Timeliif (!isTimelineId(id) || !raw || typeof raw !== "object") continue;const body = raw as Partial<Record<keyof TimelineBody, unknown>>;const subtitles = body.subtitles as SubtitlesBlock | undefined;+ const aspect =+ normalizeAspect(typeof body.aspect === "string" ? body.aspect : null) ??+ prior?.timelines?.[id]?.aspect ??+ normalizeAspect(prior?.aspect);out[id] = {clips: list(body.clips),audioClips: list(body.audioClips),@@ -1620,6 +1659,7 @@ export function sanitizeTimelines(v: unknown): Partial<Record<TimelineId, Timelioverlays: list(body.overlays),subtitles:subtitles && typeof subtitles === "object" && Array.isArray(subtitles.cues) ? subtitles : emptySubtitles(),+ ...(aspect ? { aspect } : {}),};}return out;@@ -1648,8 +1688,8 @@ export interface ProjectDoc {* docs. Read on open and merged into `clips`; new saves never write it. */overlayClips?: VideoClip[];overlays: Overlay[];- /** The timeline the top-level clips, audio, transitions, elements and- * subtitles belong to; absent = main. */+ /** The timeline the top-level clips, audio, transitions, elements,+ * subtitles and aspect belong to; absent = main. */timeline?: TimelineId;/** The closed timelines' content, parked until one is opened. */timelines?: Partial<Record<TimelineId, TimelineBody>>;diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.tsindex 1f69314c..e6df90fb 100644--- a/site/src/cut/server/ai/catalog.ts+++ b/site/src/cut/server/ai/catalog.ts@@ -226,14 +226,14 @@ export const REQUEST_TOOLS_DEF: AiToolDef = {/** Deep documentation the model can pull in on demand. */export const AI_SKILLS: Record<string, string> = {"editor-overview": `# Cut editor overview-Cut is a local, project-based short-video editor. Each project has an output aspect ratio "W:H" — presets 16:9, 9:16, 1:1, 4:3, 3:4, 2:1, or any custom ratio like 9:5 — rendered with the frame's short side at 1080px and switchable from the pill in the top bar; the current one is in editor_state project.aspect. The Guides button beside the timeline zoom turns on preview guides — thirds, center, safe margins, the short-form keep-out zone shared by TikTok, Reels and Shorts, and custom lines the user drags into place (set_guides) — which editor_state project.guides reports with the safeArea they leave. Layout:+Cut is a local, project-based short-video editor. Each timeline has its own output aspect ratio "W:H" — presets 16:9, 9:16, 1:1, 4:3, 3:4, 2:1, or any custom ratio like 9:5 — rendered with the frame's short side at 1080px and switchable from the pill in the top bar; the current one is in editor_state project.aspect. The Guides button beside the timeline zoom turns on preview guides — thirds, center, safe margins, the short-form keep-out zone shared by TikTok, Reels and Shorts, and custom lines the user drags into place (set_guides) — which editor_state project.guides reports with the safeArea they leave. Layout:- Left icon rail tabs: Media (user-imported files + Exports list), Library (shared reusable assets), Video (stock clip browser — footage + talking characters — beside the AI video generator), Image (stock images beside the AI image generator), Audio (AI voiceover + audio files), Text (title presets), Subtitles (transcript editor), Publish (caption/tags/sound metadata). Camera/mic recording lives in the top bar next to the aspect picker.- Media shows only what the user imported. Everything Cut makes carries an origin tag (generated, voiceover, recording, stock, freeze, chat, block — see \`media\` in editor_state) and lives where it was created — media you make previews on a card in this chat, panel renders sit in their job lists; a "…" menu on each files it into Media or the Library, and every card drags onto the timeline. Deleting a chat thread deletes the chat media the user never placed or filed away.- Media metadata includes fileName, sizeBytes, duration, width and height when known. File size is measured in bytes; duration is in seconds. Call get_asset_info for a source whose sizeBytes is missing.- Center: the video preview canvas (composited at the project's frame size) with draggable text overlays and subtitle captions.- Right: the Inspector — its content follows the selection (video clip, overlay video, soundtrack clip, title, or cue).- Bottom: the timeline (resizable by dragging its top border). Rows top-to-bottom: the video tracks in z-order (positive tracks, then track 0, then negative tracks behind it), soundtrack lanes (green), titles (purple), subtitle tracks (amber, when enabled). Every track is free-positioned in time.-- A project has ${TIMELINE_IDS.length} timelines (${TIMELINE_IDS.map((id) => TIMELINE_LABELS[id]).join(", ")}), picked from the menu at the left of the timeline toolbar. Each holds its own clips, soundtrack, transitions, elements and subtitles over the shared media and frame. editor_state project.timeline names the open one; the preview, the export and every edit work on it, and switch_timeline opens another.+- A project has ${TIMELINE_IDS.length} timelines (${TIMELINE_IDS.map((id) => TIMELINE_LABELS[id]).join(", ")}), picked from the menu at the left of the timeline toolbar. Each holds its own clips, soundtrack, transitions, elements, subtitles and aspect ratio over the shared media. editor_state project.timeline names the open one; the preview, the export and every edit work on it, and switch_timeline opens another.Everything autosaves to the project folder. Undo/redo is unlimited (⌘Z / ⇧⌘Z).Times are in seconds on the shared timeline. The playhead is currentTime; a skimmer previews under the mouse without moving the playhead.`,diff --git a/site/src/cut/server/cloud/projects.ts b/site/src/cut/server/cloud/projects.tsindex e6660d27..5d69ace3 100644--- a/site/src/cut/server/cloud/projects.ts+++ b/site/src/cut/server/cloud/projects.ts@@ -222,7 +222,7 @@ export const projectsCloud = {: existing.overlayClips,overlays: Array.isArray(body.overlays) ? body.overlays : existing.overlays,timeline: isTimelineId(body.timeline) ? body.timeline : existing.timeline,- timelines: sanitizeTimelines(body.timelines) ?? existing.timelines,+ timelines: sanitizeTimelines(body.timelines, existing) ?? existing.timelines,templates: Array.isArray(body.templates) ? body.templates : existing.templates,mediaFolders: Array.isArray(body.mediaFolders) ? body.mediaFolders : existing.mediaFolders,aspect: normalizeAspect(body.aspect) ?? existing.aspect,diff --git a/site/src/cut/server/cloud/sharedView.test.ts b/site/src/cut/server/cloud/sharedView.test.tsindex 69145b5d..b450a53d 100644--- a/site/src/cut/server/cloud/sharedView.test.ts+++ b/site/src/cut/server/cloud/sharedView.test.ts@@ -112,16 +112,22 @@ describe("filterDocForShare", () => {...doc,timeline: "second",clips: [{ id: "c2", assetId: "imported", track: 0, start: 0, in: 0, out: 1, muted: false }],- timelines: { main: { clips: doc.clips, audioClips: [], transitions: [], overlays: [], subtitles: { cues: [] } } },+ aspect: "16:9",+ timelines: { main: { clips: doc.clips, audioClips: [], transitions: [], overlays: [], subtitles: { cues: [] }, aspect: "9:16" } },} as unknown as ProjectDoc;const main = filterDocForShare(onSecond, features());expect(main.clips.map((c) => c.id)).toEqual(["c1"]);expect(ids(main)).toEqual(["placed"]);expect(main.timelines).toBeUndefined();+ expect(main.aspect).toBe("9:16");expect([...sharedFileNames(onSecond, features())]).toEqual(["placed.mp4"]);const second = filterDocForShare(onSecond, features({ timeline: "second" }));expect(second.clips.map((c) => c.id)).toEqual(["c2"]);+ expect(second.aspect).toBe("16:9");expect(ids(second)).toEqual(["imported"]);- expect(filterDocForShare(onSecond, features({ timeline: "third" })).clips).toEqual([]);+ const third = filterDocForShare(onSecond, features({ timeline: "third" }));+ expect(third.clips).toEqual([]);+ // Never opened: Main's frame.+ expect(third.aspect).toBe("9:16");});});diff --git a/site/src/cut/server/cloud/sharedView.ts b/site/src/cut/server/cloud/sharedView.tsindex 3c089970..82527084 100644--- a/site/src/cut/server/cloud/sharedView.ts+++ b/site/src/cut/server/cloud/sharedView.ts@@ -5,7 +5,7 @@ import { listChatThreads } from "./chats";// the content boundary: the filtered doc and the media allowlist are what// decide which bytes a viewer can reach; the client's tab hiding is// presentation only. Copying a share lives in copyQueue.ts.-import { isTimelineId, sanitizeTimelines, uploadedFontId, type ProjectDoc, type StoredAsset } from "@/cut/lib/types";+import { isTimelineId, normalizeAspect, parkedTimeline, sanitizeTimelines, uploadedFontId, type ProjectDoc, type StoredAsset } from "@/cut/lib/types";import { auth } from "@/lib/auth";import { prisma } from "@/lib/prisma";import { readLadder } from "./ladderStore";@@ -119,16 +119,9 @@ function sharedTimelineDoc(doc: ProjectDoc, features: ShareFeatures): ProjectDocwant === open? doc: (() => {- const body = sanitizeTimelines(doc.timelines)?.[want];- return {- ...doc,- clips: body?.clips ?? [],- audioClips: body?.audioClips ?? [],- transitions: body?.transitions ?? [],- overlays: body?.overlays ?? [],- subtitles: body?.subtitles,- overlayClips: undefined,- };+ const aspect = normalizeAspect(doc.aspect) ?? "9:16";+ const timelines = sanitizeTimelines(doc.timelines, { aspect }) ?? {};+ return { ...doc, ...parkedTimeline({ aspect, timeline: open, timelines }, want), overlayClips: undefined };})();return { ...cut, timeline: undefined, timelines: undefined };}diff --git a/site/src/cut/server/http/projects.ts b/site/src/cut/server/http/projects.tsindex 46961f38..773dc98d 100644--- a/site/src/cut/server/http/projects.ts+++ b/site/src/cut/server/http/projects.ts@@ -135,7 +135,7 @@ export const projectsApi = {: existing.overlayClips,overlays: Array.isArray(body.overlays) ? body.overlays : existing.overlays,timeline: isTimelineId(body.timeline) ? body.timeline : existing.timeline,- timelines: sanitizeTimelines(body.timelines) ?? existing.timelines,+ timelines: sanitizeTimelines(body.timelines, existing) ?? existing.timelines,templates: Array.isArray(body.templates) ? body.templates : existing.templates,mediaFolders: Array.isArray(body.mediaFolders) ? body.mediaFolders : existing.mediaFolders,aspect: normalizeAspect(body.aspect) ?? existing.aspect,