ipmotionmc
diff --git a/‎README.md‎
Lines changed: 68 additions & 15 deletions b/‎README.md‎
Lines changed: 68 additions & 15 deletions
diff --git a/‎backends/ts/package.json‎
Lines changed: 3 additions & 2 deletions b/‎backends/ts/package.json‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎backends/ts/src/ffmpeg.ts‎
Lines changed: 119 additions & 1 deletion b/‎backends/ts/src/ffmpeg.ts‎
Lines changed: 119 additions & 1 deletion
diff --git a/‎backends/ts/src/keyframe-expression.ts‎
Lines changed: 24 additions & 16 deletions b/‎backends/ts/src/keyframe-expression.ts‎
Lines changed: 24 additions & 16 deletions
@@ -189,14 +189,18 @@ Switching at runtime is a regular prop change — the toolbar re-titles and the
 
 ## 🧩 Custom slots
 
-Four host-fillable slots on the editor — empty by default, no chrome cost. The same pattern is the standalone `<Timeline>`'s `toolbarLeft`/`toolbarRight` props.
+Six host-fillable slots on the editor — empty by default, no chrome cost. The same pattern is the standalone `<Timeline>`'s `toolbarLeft`/`toolbarRight` props.
 
 | Slot | Where | Typical use |
 | :--- | :--- | :--- |
 | `headerLeft` | Top header, left | Project name, file menu, breadcrumbs |
 | `headerRight` | Top header, right | Share / Export / profile / settings |
-| `toolbarLeft` | Toolbar, left bookend | Aspect ratio, size, branding |
+| `toolbarLeft` | Toolbar, left bookend | Project name, status pill, branding |
 | `toolbarRight` | Toolbar, right bookend | Custom action icons |
+| `panelLeft` | Main row, left of preview (centered layout) | Source library, media bin, generators |
+| `panelRight` | Main row, right of preview (centered layout) | Inspector, properties, AI tools |
+
+The two `panel*` slots only render when `previewLayout="centered"` (the default — see [Preview layout](#-preview-layout-3-column--full-width) below). The aspect chip is now built into the toolbar, so `toolbarLeft` is free for whatever else.
 
 When both `headerLeft` and `headerRight` are empty the header bar collapses entirely — the default editor layout is byte-for-byte identical to before the slots existed.
 
@@ -213,25 +217,61 @@ When both `headerLeft` and `headerRight` are empty the header bar collapses enti
     </>
   }
   // Toolbar bookends — independent slots.
-  toolbarLeft={
-    <select value={aspect} onChange={(e) => setAspect(e.target.value)}>
-      <option value="16:9">16:9</option>
-      <option value="9:16">9:16</option>
-      <option value="1:1">1:1</option>
-    </select>
-  }
-  toolbarRight={
-    <button onClick={() => apiRef.current?.requestExport()}>Export</button>
-  }
+  toolbarLeft={<ProjectNameInput value={name} onChange={setName} />}
+  toolbarRight={<ExportStatusPill status={exportStatus} />}
+  // CapCut-desktop-style side rails — only render in centered layout.
+  panelLeft={<MediaBin sources={sources} onPickClip={addClip} />}
+  panelRight={<InspectorPanel clip={selectedClip} />}
 />
 ```
 
 ---
 
+## 🖼 Preview layout (3-column / full-width)
+
+The editor ships two top-level layouts, picked via `previewLayout`:
+
+| Layout | Behaviour | When to use |
+| :--- | :--- | :--- |
+| `"centered"` (default) | Preview lives in a width-capped card in the middle third of the row, with `panelLeft` / `panelRight` slots flanking it. | CapCut-desktop posture — host owns a media library / inspector. |
+| `"fullWidth"` | Preview spans the entire row, no side columns. | Embeds where the host doesn't need side panels. |
+
+Playback controls (time · play · duration · fullscreen) sit as a footer on the preview card in both layouts, not on top of the canvas — keyframe handles and the canvas guide stay unobstructed.
+
+```tsx
+<VideoEditor
+  previewLayout="centered"      // or "fullWidth"
+  panelLeft={<MediaBin />}
+  panelRight={<Inspector />}
+/>
+```
+
+The layout switch is reactive — flip the prop and the chrome rearranges without remounting the editor.
+
+---
+
+## 🖍 Project canvas
+
+Every spatial value in a project — keyframe `panX`/`panY`, the canvas guide rect, the export resolution — lives in **one coordinate system**, the project canvas:
+
+```ts
+project.output = { width: 1920, height: 1080, fps: 30 };
+```
+
+The preview is just a scaled view of this canvas. The export writes exactly these dimensions. Pan/scale are in canvas pixels, not preview pixels, so a project authored on a 720×720 tab and rendered on a 4K screen lands every transform identically.
+
+- `editor.setAspect("9:16")` updates `Project.output` to the 1080p tier for that ratio (1080×1920). Hosts can override with `editor.setOutput({ width, height, fps })`.
+- The backend export reads `Project.output` first; explicit `output` in the request body overrides.
+- Legacy projects without `output`: `normalizeProject` derives one from `aspect` or the first clip's intrinsic source dims (CapCut "Original" behaviour), so old JSON round-trips without manual migration.
+
+---
+
 ## 🎞 Keyframe animation
 
 CapCut-style **per-property keyframes** for `panX`, `panY`, and `scale` — pin a value at any moment, the engine animates between them. Authored in the editor, previewed live by any playback engine, **compiled to ffmpeg expressions on export** so the rendered mp4 matches the preview frame-for-frame.
 
+`panX` / `panY` are stored in **canvas pixels** of `Project.output` (see [Project canvas](#-project-canvas)). One pan unit = one pixel in the export, regardless of preview size — so the same project rendered on a small embed and a full-screen tab lands every keyframe in the same place.
+
 ```ts
 clip.keyframes = [
   { id: "k1", prop: "scale", time: 0,    value: 1                       },
@@ -244,7 +284,7 @@ clip.keyframes = [
 | :--- | :--- |
 | **Per-property model** | `panX` / `panY` / `scale` animate independently. Pre-easing tuple-keyframes auto-migrate via `normalizeProject`. |
 | **Easing curves** | `linear` / `easeIn` / `easeOut` / `easeInOut` (cubic). Stored on the leaving kf — matches AE / Premiere / CapCut convention. Omitted = linear (back-compat). |
-| **Editor UI** | Toolbar diamond toggle, draggable preview overlay (translate body / scale corners / pinch wheel), floating numeric panel with easing dropdown, **timeline diamond markers** with drag-to-retime + snap. |
+| **Editor UI** | Toolbar diamond toggle, draggable preview overlay (translate body / scale corners / pinch wheel), floating numeric panel with easing dropdown, **timeline diamond markers** with drag-to-retime (drags the whole moment — every prop pinned at the same time travels together) + snap. |
 | **Backend export** | `compileKeyframeExpression` emits a `gte(t,A)*lt(t,B)*…` sum compiled into `scale=...:eval=frame` + `overlay=…:eval=frame` filters. Both `@aicut/backend-ts` and `@aicut/backend-go` support it identically. |
 | **PiP semantics** | Output frame is fixed; pan/scale moves the *content* inside it (`overflow: hidden` in the HTML engine, `ctx.clip()` in canvas, ffmpeg `overlay` onto a fixed-size `color` background on the backend). |
 | **Lossless splits** | `splitClipAt` mid-segment **inserts interpolated boundary keyframes** so cutting and not moving the halves plays back identically to the un-cut clip. |
@@ -291,10 +331,17 @@ POST /export                                    Content-Type: application/json
   data: {"phase":"concat","overall":0.99,"totalClips":3}
   data: {"phase":"done","fileUrl":"/files/<uuid>.mp4","id":"<uuid>"}
 
-GET  /files/<uuid>.mp4                          → video/mp4
+POST /upload (multipart, field "file")          → { url, id, name }
+GET  /files/<uuid>.<ext>                        → video/* (with HTTP Range support)
 ```
 
-`out_time_us` from ffmpeg's `-progress` stream is aggregated across the per-clip encode passes, so the overall fraction is honest end-to-end. Aborting the client connection (or AbortController on the fetch) kills the in-flight ffmpeg.
+Output dimensions resolve in priority order: explicit `output` in the request body → `Project.output` → ffprobe of the bottom track's first clip → 1920×1080. With `Project.output` set (default behaviour from the editor), the request body's `output` is purely an override.
+
+The TS backend runs the entire timeline through a **single `filter_complex` pass** — bottom track painted onto a black `color=` canvas first, each higher track overlaid with `enable='between(t,start,end)'` so PiP windows respect their lifetimes. Keyframe `panX`/`panY`/`scale` compile to per-frame ffmpeg expressions; the compositor renders at 2× internal resolution and downsamples with lanczos so sub-pixel motion stays smooth. Audio: only the top track contributes (matching the editor's PiP policy), mixed via `amix`.
+
+`out_time_us` from ffmpeg's `-progress` stream feeds the overall fraction. Aborting the client connection (or AbortController on the fetch) kills the in-flight ffmpeg.
+
+The Go backend still uses the per-clip + concat strategy and ignores cross-track compositing — slated for parity in a follow-up release.
 
 <div align="center">
 
@@ -497,6 +544,12 @@ The script is idempotent — already-published versions are skipped, so a re-run
 - [x] Density knobs — `timelineHeight` (reactive), `trackHeight`, `rulerHeight` for compact viewports
 - [x] Per-clip keyframe animation (X / Y / Scale) + easing curves (linear / easeIn / easeOut / easeInOut)
 - [x] Backend ffmpeg compilation of keyframes — animated `scale` + `overlay` filter graph with per-frame `t`-expressions, both TS + Go
+- [x] Multi-track timeline export (PiP-aware compositor in TS backend — single `filter_complex` pass with per-track overlay + `enable` windows)
+- [x] Source-of-truth project canvas (`Project.output`) — pan/scale in canvas pixels, preview/export pixel-for-pixel
+- [x] 3-column preview layout + `panelLeft`/`panelRight` host slots (CapCut-desktop posture)
+- [x] Frame-aware timeline ruler — seconds first, frame sub-ticks at high zoom (`rulerMinTickPx` knob)
+- [x] Backend upload endpoint + HTTP Range support (QuickTime `.mov` with trailing moov streams correctly)
+- [ ] Go backend parity with TS multi-track compositor
 - [ ] Speed adjustment (timeline already reserves the slot)
 - [ ] Audio track rendering + waveform thumbnails
 - [ ] WebCodecs engine: multi-track compositing + transitions
 
@@ -13,8 +13,9 @@
   },
   "dependencies": {
     "@aicut/core": "workspace:*",
-    "fastify": "^5.2.0",
-    "@fastify/cors": "^10.0.1"
+    "@fastify/cors": "^10.0.1",
+    "@fastify/multipart": "^10.0.0",
+    "fastify": "^5.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
 
@@ -22,6 +22,119 @@ export async function resolveFfmpeg(): Promise<string> {
   return "ffmpeg";
 }
 
+/** Resolve ffprobe alongside ffmpeg, with the same precedence. */
+export async function resolveFfprobe(): Promise<string> {
+  const envBin = process.env["AICUT_FFPROBE"];
+  if (envBin && (await fileExists(envBin))) return envBin;
+
+  const bundled = path.resolve(__dirname, "..", "ffmpeg-bin", "ffprobe");
+  if (await fileExists(bundled)) return bundled;
+
+  return "ffprobe";
+}
+
+/** Same proxy-strip env used by ffmpeg subprocesses — see runFfmpeg
+ *  for the why. Exported so ffprobe spawns can share it. */
+function noProxyEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  delete env.HTTP_PROXY;
+  delete env.http_proxy;
+  delete env.HTTPS_PROXY;
+  delete env.https_proxy;
+  delete env.ALL_PROXY;
+  delete env.all_proxy;
+  env.NO_PROXY = "localhost,127.0.0.1,::1";
+  env.no_proxy = "localhost,127.0.0.1,::1";
+  return env;
+}
+
+/**
+ * Probe a source's intrinsic video dimensions. Used to derive the
+ * export canvas size when the client doesn't pass one, matching the
+ * frontend's `canvasReferenceDims` (= first video clip on the bottom
+ * track). Returns null on any failure — caller decides the fallback.
+ */
+export async function probeVideoDimensions(
+  ffprobeBin: string,
+  url: string,
+): Promise<{ width: number; height: number } | null> {
+  return new Promise((resolve) => {
+    const proc = spawn(
+      ffprobeBin,
+      [
+        "-v",
+        "error",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=width,height",
+        "-of",
+        "csv=p=0",
+        url,
+      ],
+      { stdio: ["ignore", "pipe", "pipe"], env: noProxyEnv() },
+    );
+    let stdout = "";
+    proc.stdout.on("data", (b: Buffer) => {
+      stdout += b.toString();
+    });
+    proc.on("error", () => resolve(null));
+    proc.on("close", () => {
+      const trimmed = stdout.trim();
+      const m = /^(\d+),(\d+)$/.exec(trimmed);
+      if (!m) return resolve(null);
+      const width = Number(m[1]);
+      const height = Number(m[2]);
+      if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        return resolve(null);
+      }
+      resolve({ width, height });
+    });
+  });
+}
+
+/**
+ * Check whether a source has at least one audio stream. The render
+ * graph hits a hard "no streams" error when we wire `[N:a]` against
+ * a video-only source (and ffmpeg's `?` modifier only helps if the
+ * sub-graph is independently dropped — chained filters trip the same
+ * error). Probe up front so we know which clips contribute audio.
+ *
+ * Failures (network error, missing binary) treat the source as
+ * audio-less rather than aborting the whole render — at worst the
+ * output is silent, which is recoverable.
+ */
+export async function probeHasAudio(
+  ffprobeBin: string,
+  url: string,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    const proc = spawn(
+      ffprobeBin,
+      [
+        "-v",
+        "error",
+        "-select_streams",
+        "a",
+        "-show_entries",
+        "stream=index",
+        "-of",
+        "csv=p=0",
+        url,
+      ],
+      { stdio: ["ignore", "pipe", "pipe"], env: noProxyEnv() },
+    );
+    let stdout = "";
+    proc.stdout.on("data", (b: Buffer) => {
+      stdout += b.toString();
+    });
+    proc.on("error", () => resolve(false));
+    proc.on("close", () => {
+      resolve(stdout.trim().length > 0);
+    });
+  });
+}
+
 async function fileExists(p: string): Promise<boolean> {
   try {
     await access(p, constants.X_OK);
@@ -56,7 +169,12 @@ export function runFfmpeg(
     // We want stdout when progress is being parsed; without an
     // onStdoutLine consumer, draining it costs nothing meaningful but
     // keeps the contract uniform.
-    const proc = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    // Strip any inherited HTTP/HTTPS proxy env vars from the ffmpeg
+    // subprocess — see noProxyEnv for the why.
+    const proc = spawn(bin, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: noProxyEnv(),
+    });
     let stderr = "";
     let stdoutBuf = "";
     proc.stdout.on("data", (b: Buffer) => {
 
@@ -2,34 +2,42 @@ import type { EasingKind, Keyframe, KeyframeProp } from "@aicut/core";
 
 /**
  * Compile a per-property keyframe array into an ffmpeg filter
- * expression in `t` (output stream timestamp, seconds). The result is
- * suitable to drop into `scale=w='...':h='...':eval=frame` or
- * `overlay=x='...':eval=frame` — both filters expose `t` as the
- * current output timestamp.
+ * expression. The result is suitable to drop into
+ * `scale=w='...':h='...':eval=frame` or `overlay=x='...':eval=frame`
+ * — both filters expose `t` as the current OUTPUT timestamp.
  *
  * Math: each segment between kf[i] and kf[i+1] contributes
  *
- *   gte(t, A) * lt(t, B) * ( a.value + easedT * (b.value - a.value) )
+ *   gte(T, A) * lt(T, B) * ( a.value + easedT * (b.value - a.value) )
  *
- * where easedT applies the LEAVING keyframe's outgoing curve to the
- * normalized progress `(t - A)/(B - A)`. Before-first holds the
+ * where `T` is the time-variable expression (default `t`) and
+ * easedT applies the LEAVING keyframe's outgoing curve to the
+ * normalized progress `(T - A)/(B - A)`. Before-first holds the
  * first value; after-last holds the last value. Boundaries use a
- * half-open `[A, B)` mask so the same t never gets counted twice.
+ * half-open `[A, B)` mask so the same T never gets counted twice.
  *
  * For props with NO keyframes the function returns the static
  * fallback as a literal so the caller can drop the result straight
  * into the filter without conditionals.
  *
- * `t` here matches the segment-local timeline because the encoder
- * runs each clip in its own ffmpeg call with `-ss` + `-t` cropping
- * the input to clip-local time. So a keyframe at clip-local 1000ms
- * compiles to `gte(t, 1.000000)` directly.
+ * `tVar` lets the caller substitute a CLIP-LOCAL expression when the
+ * filter sees global timeline `t` — e.g. when compositing multiple
+ * tracks in a single filter_complex pass, callers pass
+ * `tVar: "(t-${clip.start/1000})"` so keyframe times stay anchored
+ * to clip start.
  */
+export interface CompileOpts {
+  /** Expression that evaluates to clip-local seconds. Defaults to `"t"`. */
+  tVar?: string;
+}
+
 export function compileKeyframeExpression(
   keyframes: Keyframe[] | undefined,
   prop: KeyframeProp,
   fallback: number,
+  opts: CompileOpts = {},
 ): string {
+  const T = opts.tVar ?? "t";
   if (!keyframes || keyframes.length === 0) return formatNumber(fallback);
   const propKfs = keyframes
     .filter((k) => k.prop === prop)
@@ -42,7 +50,7 @@ export function compileKeyframeExpression(
   const last = propKfs[propKfs.length - 1]!;
 
   // Before first kf — held at first.value.
-  parts.push(`lt(t,${formatTime(first.time)})*${formatNumber(first.value)}`);
+  parts.push(`lt(${T},${formatTime(first.time)})*${formatNumber(first.value)}`);
 
   // Segments.
   for (let i = 0; i < propKfs.length - 1; i += 1) {
@@ -52,18 +60,18 @@ export function compileKeyframeExpression(
     const bSec = formatTime(b.time);
     const dur = (b.time - a.time) / 1000;
     if (dur <= 0) continue; // zero-length segment — skip to avoid div/0
-    const rawT = `(t-${aSec})/${formatNumber(dur)}`;
+    const rawT = `(${T}-${aSec})/${formatNumber(dur)}`;
     const easedT = easingExpression(rawT, a.easing ?? "linear");
     const delta = b.value - a.value;
     const lerpedExpr =
       delta === 0
         ? formatNumber(a.value) // value held — constant segment
         : `(${formatNumber(a.value)}+(${easedT})*(${formatNumber(delta)}))`;
-    parts.push(`gte(t,${aSec})*lt(t,${bSec})*${lerpedExpr}`);
+    parts.push(`gte(${T},${aSec})*lt(${T},${bSec})*${lerpedExpr}`);
   }
 
   // After last kf — held at last.value.
-  parts.push(`gte(t,${formatTime(last.time)})*${formatNumber(last.value)}`);
+  parts.push(`gte(${T},${formatTime(last.time)})*${formatNumber(last.value)}`);
 
   return parts.join("+");
 }