feat: masks, properties refactor, shaders, storage migrations, and more

2026-07-13 21:52:53 +02:00 · 2026-03-29 15:48:22 +02:00
parent 39ea298a9c
commit 8db3bead13
690 changed files with 35618 additions and 7337 deletions
@@ -1,194 +1,191 @@
 import { createOffscreenCanvas } from "./canvas-utils";
-import { getEffect } from "@/lib/effects";
-import type { EffectParamValues } from "@/types/effects";
-import { applyMultiPassEffect } from "./webgl-utils";
-import type { EffectPassData } from "./webgl-utils";
+import { effectsRegistry, resolveEffectPasses } from "@/lib/effects";
+import { buildDefaultParamValues } from "@/lib/registry";
+import type { ParamValues } from "@/lib/params";
+import { applyMultiPassEffect } from "./webgl/webgl-utils";
+import type { EffectPassData } from "./webgl/webgl-utils";

 const PREVIEW_SIZE = 160;
 const PREVIEW_IMAGE_PATH = "/effects/preview.jpg";

-let previewGl: WebGLRenderingContext | null = null;
-let previewCanvas: OffscreenCanvas | HTMLCanvasElement | null = null;
-let testSourceCanvas: OffscreenCanvas | HTMLCanvasElement | null = null;
-let previewImageElement: HTMLImageElement | null = null;
-const programCache = new Map<string, WebGLProgram>();
-const onReadyCallbacks = new Set<() => void>();
+class EffectPreviewService {
+	private previewGl: WebGLRenderingContext | null = null;
+	private previewCanvas: OffscreenCanvas | HTMLCanvasElement | null = null;
+	private testSourceCanvas: OffscreenCanvas | HTMLCanvasElement | null = null;
+	private previewImageElement: HTMLImageElement | null = null;
+	private programCache = new Map<string, WebGLProgram>();
+	private onReadyCallbacks = new Set<() => void>();

-export function onPreviewImageReady({
-	callback,
-}: {
-	callback: () => void;
-}): () => void {
-	onReadyCallbacks.add(callback);
-	return () => onReadyCallbacks.delete(callback);
-}
+	readonly PREVIEW_SIZE = PREVIEW_SIZE;

-function loadPreviewImage(): void {
-	if (typeof window === "undefined") return;
-	const image = new Image();
-	image.onload = () => {
-		testSourceCanvas = null;
-		for (const callback of onReadyCallbacks) {
-			callback();
-		}
-	};
-	image.src = PREVIEW_IMAGE_PATH;
-	previewImageElement = image;
-}
-
-loadPreviewImage();
-
-function buildDefaultParams({
-	effectType,
-}: {
-	effectType: string;
-}): EffectParamValues {
-	const definition = getEffect({ effectType });
-	const params: EffectParamValues = {};
-	for (const paramDef of definition.params) {
-		params[paramDef.key] = paramDef.default;
-	}
-	return params;
-}
-
-function createTestSource({
-	width,
-	height,
-}: {
-	width: number;
-	height: number;
-}): OffscreenCanvas | HTMLCanvasElement | null {
-	const isImageReady =
-		previewImageElement?.complete &&
-		(previewImageElement.naturalWidth ?? 0) > 0;
-	if (!isImageReady || !previewImageElement) {
-		return null;
+	constructor() {
+		this.loadPreviewImage();
 	}

-	const canvas = createOffscreenCanvas({ width, height });
-	const ctx = canvas.getContext("2d") as
-		| CanvasRenderingContext2D
-		| OffscreenCanvasRenderingContext2D
-		| null;
-	if (!ctx) {
-		throw new Error("failed to get 2d context for test source");
+	onPreviewImageReady({
+		callback,
+	}: {
+		callback: () => void;
+	}): () => void {
+		this.onReadyCallbacks.add(callback);
+		return () => this.onReadyCallbacks.delete(callback);
 	}
-	ctx.drawImage(previewImageElement, 0, 0, width, height);
-	return canvas;
-}

-function getOrCreatePreviewContext({
-	width,
-	height,
-}: {
-	width: number;
-	height: number;
-}): { canvas: OffscreenCanvas | HTMLCanvasElement; gl: WebGLRenderingContext } {
-	if (!previewCanvas || !previewGl) {
-		previewCanvas = createOffscreenCanvas({ width, height });
-		previewGl = previewCanvas.getContext("webgl", {
-			premultipliedAlpha: false,
-		}) as WebGLRenderingContext | null;
-		if (!previewGl) {
-			throw new Error("WebGL not supported");
-		}
-	}
-	if (previewCanvas.width !== width || previewCanvas.height !== height) {
-		previewCanvas.width = width;
-		previewCanvas.height = height;
-	}
-	return { canvas: previewCanvas, gl: previewGl };
-}
+	renderPreview({
+		effectType,
+		params,
+		targetCanvas,
+		uniformDimensions,
+	}: {
+		effectType: string;
+		params: ParamValues;
+		targetCanvas: HTMLCanvasElement;
+		uniformDimensions?: { width: number; height: number };
+	}): void {
+		const size = PREVIEW_SIZE;
+		const source = this.getTestSource({ width: size, height: size });
+		if (!source) return;

-function getTestSource({
-	width,
-	height,
-}: {
-	width: number;
-	height: number;
-}): CanvasImageSource | null {
-	if (
-		!testSourceCanvas ||
-		testSourceCanvas.width !== width ||
-		testSourceCanvas.height !== height
-	) {
-		testSourceCanvas = createTestSource({ width, height });
-	}
-	return testSourceCanvas;
-}
+		const definition = effectsRegistry.get(effectType);
+		const resolvedParams =
+			Object.keys(params).length > 0
+				? params
+				: buildDefaultParamValues(definition.params);

-function applyWebGlEffect({
-	source,
-	width,
-	height,
-	passes,
-}: {
-	source: CanvasImageSource;
-	width: number;
-	height: number;
-	passes: EffectPassData[];
-}): OffscreenCanvas | HTMLCanvasElement {
-	const { canvas: glCanvas, gl } = getOrCreatePreviewContext({ width, height });
-
-	applyMultiPassEffect({ context: gl, source, width, height, passes, programCache });
-
-	const outputCanvas = createOffscreenCanvas({ width, height });
-	const outputCtx = outputCanvas.getContext("2d") as
-		| CanvasRenderingContext2D
-		| OffscreenCanvasRenderingContext2D
-		| null;
-	if (outputCtx) {
-		outputCtx.drawImage(glCanvas, 0, 0, width, height);
-	}
-	return outputCanvas;
-}
-
-export function renderPreview({
-	effectType,
-	params,
-	targetCanvas,
-}: {
-	effectType: string;
-	params: EffectParamValues;
-	targetCanvas: HTMLCanvasElement;
-}): void {
-	const size = PREVIEW_SIZE;
-	const source = getTestSource({ width: size, height: size });
-	if (!source) return;
-
-	const definition = getEffect({ effectType });
-	const resolvedParams =
-		Object.keys(params).length > 0
-			? params
-			: buildDefaultParams({ effectType });
-
-	const passes = definition.renderer.passes.map((pass) => ({
-		fragmentShader: pass.fragmentShader,
-		uniforms: pass.uniforms({
+		const passes = resolveEffectPasses({
+			definition,
 			effectParams: resolvedParams,
+			width: uniformDimensions?.width ?? size,
+			height: uniformDimensions?.height ?? size,
+		});
+		const result = this.applyWebGlEffect({
+			source,
 			width: size,
 			height: size,
-		}),
-	}));
-	const result = applyWebGlEffect({
-		source,
-		width: size,
-		height: size,
-		passes,
-	});
+			passes,
+		});

-	const targetCtx = targetCanvas.getContext(
-		"2d",
-	) as CanvasRenderingContext2D | null;
-	if (targetCtx) {
-		targetCanvas.width = size;
-		targetCanvas.height = size;
-		targetCtx.drawImage(result, 0, 0, size, size);
+		const targetCtx = targetCanvas.getContext(
+			"2d",
+		) as CanvasRenderingContext2D | null;
+		if (targetCtx) {
+			targetCanvas.width = size;
+			targetCanvas.height = size;
+			targetCtx.drawImage(result, 0, 0, size, size);
+		}
+	}
+
+	private loadPreviewImage(): void {
+		if (typeof window === "undefined") return;
+		const image = new Image();
+		image.onload = () => {
+			this.testSourceCanvas = null;
+			for (const callback of this.onReadyCallbacks) {
+				callback();
+			}
+		};
+		image.src = PREVIEW_IMAGE_PATH;
+		this.previewImageElement = image;
+	}
+
+	private createTestSource({
+		width,
+		height,
+	}: {
+		width: number;
+		height: number;
+	}): OffscreenCanvas | HTMLCanvasElement | null {
+		const isImageReady =
+			this.previewImageElement?.complete &&
+			(this.previewImageElement.naturalWidth ?? 0) > 0;
+		if (!isImageReady || !this.previewImageElement) {
+			return null;
+		}
+
+		const canvas = createOffscreenCanvas({ width, height });
+		const ctx = canvas.getContext("2d") as
+			| CanvasRenderingContext2D
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (!ctx) {
+			throw new Error("failed to get 2d context for test source");
+		}
+		ctx.drawImage(this.previewImageElement, 0, 0, width, height);
+		return canvas;
+	}
+
+	private getOrCreatePreviewContext({
+		width,
+		height,
+	}: {
+		width: number;
+		height: number;
+	}): { canvas: OffscreenCanvas | HTMLCanvasElement; gl: WebGLRenderingContext } {
+		if (!this.previewCanvas || !this.previewGl) {
+			this.previewCanvas = createOffscreenCanvas({ width, height });
+			this.previewGl = this.previewCanvas.getContext("webgl", {
+				premultipliedAlpha: false,
+			}) as WebGLRenderingContext | null;
+			if (!this.previewGl) {
+				throw new Error("WebGL not supported");
+			}
+		}
+		if (this.previewCanvas.width !== width || this.previewCanvas.height !== height) {
+			this.previewCanvas.width = width;
+			this.previewCanvas.height = height;
+		}
+		return { canvas: this.previewCanvas, gl: this.previewGl };
+	}
+
+	private getTestSource({
+		width,
+		height,
+	}: {
+		width: number;
+		height: number;
+	}): CanvasImageSource | null {
+		if (
+			!this.testSourceCanvas ||
+			this.testSourceCanvas.width !== width ||
+			this.testSourceCanvas.height !== height
+		) {
+			this.testSourceCanvas = this.createTestSource({ width, height });
+		}
+		return this.testSourceCanvas;
+	}
+
+	private applyWebGlEffect({
+		source,
+		width,
+		height,
+		passes,
+	}: {
+		source: CanvasImageSource;
+		width: number;
+		height: number;
+		passes: EffectPassData[];
+	}): OffscreenCanvas | HTMLCanvasElement {
+		const { canvas: glCanvas, gl } = this.getOrCreatePreviewContext({ width, height });
+
+		applyMultiPassEffect({
+			context: gl,
+			source,
+			width,
+			height,
+			passes,
+			programCache: this.programCache,
+		});
+
+		const outputCanvas = createOffscreenCanvas({ width, height });
+		const outputCtx = outputCanvas.getContext("2d") as
+			| CanvasRenderingContext2D
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (outputCtx) {
+			outputCtx.drawImage(glCanvas, 0, 0, width, height);
+		}
+		return outputCanvas;
 	}
 }

-export const effectPreviewService = {
-	renderPreview,
-	onPreviewImageReady,
-	PREVIEW_SIZE,
-};
+export const effectPreviewService = new EffectPreviewService();
@@ -0,0 +1,54 @@
+import jfaDistanceShader from "@/lib/masks/shaders/jfa-distance.frag.glsl";
+import { getWebGLContext, readResult } from "./webgl/webgl-context";
+import { computeSignedDistanceField, runPass } from "./webgl/jfa";
+import { compileProgram, createTexture } from "./webgl/webgl-utils";
+
+export function applyMaskFeather({
+	maskCanvas,
+	width,
+	height,
+	feather,
+}: {
+	maskCanvas: CanvasImageSource;
+	width: number;
+	height: number;
+	feather: number;
+}): OffscreenCanvas | HTMLCanvasElement {
+	const { context, programCache } = getWebGLContext({ width, height });
+	const sourceTexture = createTexture({ context, source: maskCanvas });
+
+	const sdf = computeSignedDistanceField({
+		context,
+		programCache,
+		sourceTexture,
+		width,
+		height,
+	});
+
+	const distanceProgram = compileProgram({
+		context,
+		fragmentShaderSource: jfaDistanceShader,
+		programCache,
+	});
+
+	runPass({
+		context,
+		program: distanceProgram,
+		inputTexture: sdf.insideTexture,
+		target: null,
+		width,
+		height,
+		uniforms: { u_feather_half: feather / 2.0 },
+		extraBindings: [
+			{ unit: 1, texture: sdf.outsideTexture, name: "u_jfa_outside" },
+		],
+	});
+
+	context.deleteTexture(sourceTexture);
+	sdf.cleanup();
+
+	context.bindTexture(context.TEXTURE_2D, null);
+	context.bindFramebuffer(context.FRAMEBUFFER, null);
+
+	return readResult({ width, height });
+}
@@ -0,0 +1,149 @@
+import { TIME_EPSILON_SECONDS } from "@/constants/animation-constants";
+import { buildGaussianBlurPasses } from "@/lib/effects/definitions/blur";
+import { getSourceTimeAtClipTime } from "@/lib/retime";
+import { videoCache } from "@/services/video-cache/service";
+import type { RetimeConfig } from "@/lib/timeline";
+import type { CanvasRenderer } from "../canvas-renderer";
+import { createOffscreenCanvas } from "../canvas-utils";
+import { webglEffectRenderer } from "../webgl/webgl-effect-renderer";
+import { BaseNode } from "./base-node";
+import { loadImageSource, type CachedImageSource } from "./image-node";
+
+export type BlurBackgroundNodeParams = {
+	mediaId: string;
+	url: string;
+	file: File;
+	mediaType: "video" | "image";
+	duration: number;
+	timeOffset: number;
+	trimStart: number;
+	trimEnd: number;
+	retime?: RetimeConfig;
+	blurIntensity: number;
+};
+
+type BackdropSource = {
+	source: CanvasImageSource;
+	width: number;
+	height: number;
+};
+
+export class BlurBackgroundNode extends BaseNode<BlurBackgroundNodeParams> {
+	private cachedImageSource: Promise<CachedImageSource> | null;
+
+	constructor(params: BlurBackgroundNodeParams) {
+		super(params);
+		this.cachedImageSource =
+			params.mediaType === "image" ? loadImageSource(params.url) : null;
+	}
+
+	private isInRange({ time }: { time: number }): boolean {
+		const localTime = time - this.params.timeOffset;
+		return (
+			localTime >= -TIME_EPSILON_SECONDS && localTime < this.params.duration
+		);
+	}
+
+	private getSourceLocalTime({ time }: { time: number }): number {
+		const clipTime = time - this.params.timeOffset;
+		return (
+			this.params.trimStart +
+			getSourceTimeAtClipTime({
+				clipTime,
+				retime: this.params.retime,
+			})
+		);
+	}
+
+	private async getBackdropSource({
+		time,
+	}: {
+		time: number;
+	}): Promise<BackdropSource | null> {
+		if (this.params.mediaType === "video") {
+			const frame = await videoCache.getFrameAt({
+				mediaId: this.params.mediaId,
+				file: this.params.file,
+				time: this.getSourceLocalTime({ time }),
+			});
+
+			if (!frame) {
+				return null;
+			}
+
+			return {
+				source: frame.canvas,
+				width: frame.canvas.width,
+				height: frame.canvas.height,
+			};
+		}
+
+		if (!this.cachedImageSource) {
+			return null;
+		}
+
+		const { source, width, height } = await this.cachedImageSource;
+		return { source, width, height };
+	}
+
+	async render({ renderer, time }: { renderer: CanvasRenderer; time: number }) {
+		await super.render({ renderer, time });
+
+		if (!this.isInRange({ time })) {
+			return;
+		}
+
+		const backdropSource = await this.getBackdropSource({ time });
+		if (!backdropSource) {
+			return;
+		}
+
+		const offscreen = createOffscreenCanvas({
+			width: renderer.width,
+			height: renderer.height,
+		});
+		const offscreenCtx = offscreen.getContext("2d") as
+			| CanvasRenderingContext2D
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (!offscreenCtx) {
+			return;
+		}
+
+		const coverScale = Math.max(
+			renderer.width / backdropSource.width,
+			renderer.height / backdropSource.height,
+		);
+		const scaledWidth = backdropSource.width * coverScale;
+		const scaledHeight = backdropSource.height * coverScale;
+		const offsetX = (renderer.width - scaledWidth) / 2;
+		const offsetY = (renderer.height - scaledHeight) / 2;
+
+		offscreenCtx.drawImage(
+			backdropSource.source,
+			offsetX,
+			offsetY,
+			scaledWidth,
+			scaledHeight,
+		);
+
+		const passes = buildGaussianBlurPasses({
+			sigmaX: this.params.blurIntensity * (renderer.width / 1920),
+			sigmaY: this.params.blurIntensity * (renderer.height / 1080),
+		});
+		const effectResult = webglEffectRenderer.applyEffect({
+			source: offscreen as CanvasImageSource,
+			width: renderer.width,
+			height: renderer.height,
+			passes,
+		});
+
+		renderer.context.drawImage(
+			effectResult,
+			0,
+			0,
+			renderer.width,
+			renderer.height,
+		);
+	}
+}
@@ -1,77 +0,0 @@
-import type { CanvasRenderer } from "../canvas-renderer";
-import { createOffscreenCanvas } from "../canvas-utils";
-import { getEffect } from "@/lib/effects";
-import type { EffectParamValues } from "@/types/effects";
-import { BaseNode } from "./base-node";
-import { webglEffectRenderer } from "../webgl-effect-renderer";
-
-export type CompositeEffectNodeParams = {
-	contentNodes: BaseNode[];
-	effectType: string;
-	effectParams: EffectParamValues;
-	scale: number;
-};
-
-export class CompositeEffectNode extends BaseNode<CompositeEffectNodeParams> {
-	async render({
-		renderer,
-		time,
-	}: {
-		renderer: CanvasRenderer;
-		time: number;
-	}): Promise<void> {
-		const offscreen = createOffscreenCanvas({
-			width: renderer.width,
-			height: renderer.height,
-		});
-		const offscreenCtx = offscreen.getContext("2d") as OffscreenCanvasRenderingContext2D | null;
-		if (!offscreenCtx) {
-			throw new Error("failed to get offscreen canvas context");
-		}
-
-		const originalContext = renderer.context;
-		renderer.context = offscreenCtx;
-
-		for (const node of this.params.contentNodes) {
-			await node.render({ renderer, time });
-		}
-
-		renderer.context = originalContext;
-
-		const effectDefinition = getEffect({ effectType: this.params.effectType });
-		const scale = this.params.scale;
-		const scaledWidth = renderer.width * scale;
-		const scaledHeight = renderer.height * scale;
-		const offsetX = (renderer.width - scaledWidth) / 2;
-		const offsetY = (renderer.height - scaledHeight) / 2;
-
-		const passes = effectDefinition.renderer.passes.map((pass) => ({
-			fragmentShader: pass.fragmentShader,
-			uniforms: pass.uniforms({
-				effectParams: this.params.effectParams,
-				width: renderer.width,
-				height: renderer.height,
-			}),
-		}));
-		const effectResult = webglEffectRenderer.applyEffect({
-			source: offscreen as CanvasImageSource,
-			width: renderer.width,
-			height: renderer.height,
-			passes,
-		});
-
-		renderer.context.save();
-		renderer.context.drawImage(
-			effectResult,
-			0,
-			0,
-			renderer.width,
-			renderer.height,
-			offsetX,
-			offsetY,
-			scaledWidth,
-			scaledHeight,
-		);
-		renderer.context.restore();
-	}
-}
@@ -1,14 +1,14 @@
 import type { CanvasRenderer } from "../canvas-renderer";
-import { getEffect } from "@/lib/effects";
-import type { EffectParamValues } from "@/types/effects";
+import { effectsRegistry, resolveEffectPasses } from "@/lib/effects";
+import type { ParamValues } from "@/lib/params";
 import { BaseNode } from "./base-node";
-import { webglEffectRenderer } from "../webgl-effect-renderer";
+import { webglEffectRenderer } from "../webgl/webgl-effect-renderer";

 const TIME_EPSILON = 1e-6;

 export type EffectLayerNodeParams = {
 	effectType: string;
-	effectParams: EffectParamValues;
+	effectParams: ParamValues;
 	timeOffset: number;
 	duration: number;
 };
@@ -49,18 +49,17 @@ export class EffectLayerNode extends BaseNode<EffectLayerNodeParams> {

 		const source = renderer.context.canvas as CanvasImageSource;

-		const effectDefinition = getEffect({
-			effectType: this.params.effectType,
-		});
+		const effectDefinition = effectsRegistry.get(this.params.effectType);

-		const passes = effectDefinition.renderer.passes.map((pass) => ({
-			fragmentShader: pass.fragmentShader,
-			uniforms: pass.uniforms({
-				effectParams: this.params.effectParams,
-				width: renderer.width,
-				height: renderer.height,
-			}),
-		}));
+		const passes = resolveEffectPasses({
+			definition: effectDefinition,
+			effectParams: this.params.effectParams,
+			width: renderer.width,
+			height: renderer.height,
+		});
+		if (passes.length === 0) {
+			return;
+		}
 		const effectResult = webglEffectRenderer.applyEffect({
 			source,
 			width: renderer.width,
@@ -0,0 +1,92 @@
+import type { CanvasRenderer } from "../canvas-renderer";
+import { createOffscreenCanvas } from "../canvas-utils";
+import {
+	DEFAULT_GRAPHIC_SOURCE_SIZE,
+	getGraphicDefinition,
+	registerDefaultGraphics,
+} from "@/lib/graphics";
+import { resolveGraphicParamsAtTime } from "@/lib/animation";
+import type { ParamValues } from "@/lib/params";
+import { VisualNode, type VisualNodeParams } from "./visual-node";
+
+export interface GraphicNodeParams extends VisualNodeParams {
+	definitionId: string;
+	params: ParamValues;
+}
+
+export class GraphicNode extends VisualNode<GraphicNodeParams> {
+	private cachedKey: string | null = null;
+	private cachedSource: OffscreenCanvas | HTMLCanvasElement | null = null;
+
+	constructor(params: GraphicNodeParams) {
+		super(params);
+		registerDefaultGraphics();
+	}
+
+	private getSource({
+		localTime,
+	}: {
+		localTime: number;
+	}): OffscreenCanvas | HTMLCanvasElement | null {
+		const definition = getGraphicDefinition({
+			definitionId: this.params.definitionId,
+		});
+		const resolvedParams = resolveGraphicParamsAtTime({
+			element: this.params,
+			localTime,
+		});
+		const cacheKey = JSON.stringify({
+			definitionId: this.params.definitionId,
+			params: resolvedParams,
+		});
+		if (this.cachedSource && this.cachedKey === cacheKey) {
+			return this.cachedSource;
+		}
+
+		const canvas = createOffscreenCanvas({
+			width: DEFAULT_GRAPHIC_SOURCE_SIZE,
+			height: DEFAULT_GRAPHIC_SOURCE_SIZE,
+		});
+		const ctx = canvas.getContext("2d") as
+			| CanvasRenderingContext2D
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (!ctx) {
+			return null;
+		}
+
+		definition.render({
+			ctx,
+			params: resolvedParams,
+			width: DEFAULT_GRAPHIC_SOURCE_SIZE,
+			height: DEFAULT_GRAPHIC_SOURCE_SIZE,
+		});
+
+		this.cachedKey = cacheKey;
+		this.cachedSource = canvas;
+		return canvas;
+	}
+
+	async render({ renderer, time }: { renderer: CanvasRenderer; time: number }) {
+		await super.render({ renderer, time });
+
+		if (!this.isInRange({ time })) {
+			return;
+		}
+
+		const source = this.getSource({
+			localTime: this.getAnimationLocalTime({ time }),
+		});
+		if (!source) {
+			return;
+		}
+
+		this.renderVisual({
+			renderer,
+			source,
+			sourceWidth: DEFAULT_GRAPHIC_SOURCE_SIZE,
+			sourceHeight: DEFAULT_GRAPHIC_SOURCE_SIZE,
+			timelineTime: time,
+		});
+	}
+}
@@ -6,7 +6,7 @@ export interface ImageNodeParams extends VisualNodeParams {
 	maxSourceSize?: number;
 }

-interface CachedImageSource {
+export interface CachedImageSource {
 	source: HTMLImageElement | OffscreenCanvas;
 	width: number;
 	height: number;
@@ -14,7 +14,7 @@ interface CachedImageSource {

 const imageSourceCache = new Map<string, Promise<CachedImageSource>>();

-function loadImageSource(
+export function loadImageSource(
 	url: string,
 	maxSourceSize?: number,
 ): Promise<CachedImageSource> {
@@ -4,6 +4,8 @@ import { VisualNode, type VisualNodeParams } from "./visual-node";

 export interface StickerNodeParams extends VisualNodeParams {
 	stickerId: string;
+	intrinsicWidth?: number;
+	intrinsicHeight?: number;
 }

 interface CachedStickerSource {
@@ -14,7 +16,7 @@ interface CachedStickerSource {

 const stickerSourceCache = new Map<string, Promise<CachedStickerSource>>();

-function loadStickerSource(stickerId: string): Promise<CachedStickerSource> {
+function loadStickerSource({ stickerId }: { stickerId: string }): Promise<CachedStickerSource> {
 	const cached = stickerSourceCache.get(stickerId);
 	if (cached) return cached;

@@ -33,7 +35,7 @@ function loadStickerSource(stickerId: string): Promise<CachedStickerSource> {
 			image.src = url;
 		});

-		return { source: image, width: 200, height: 200 };
+		return { source: image, width: image.naturalWidth, height: image.naturalHeight };
 	})();

 	stickerSourceCache.set(stickerId, promise);
@@ -45,7 +47,7 @@ export class StickerNode extends VisualNode<StickerNodeParams> {

 	constructor(params: StickerNodeParams) {
 		super(params);
-		this.cachedSource = loadStickerSource(params.stickerId);
+		this.cachedSource = loadStickerSource({ stickerId: params.stickerId });
 	}

 	async render({ renderer, time }: { renderer: CanvasRenderer; time: number }) {
@@ -55,13 +57,19 @@ export class StickerNode extends VisualNode<StickerNodeParams> {
 			return;
 		}

-		const { source, width, height } = await this.cachedSource;
+		const { source, width: loadedWidth, height: loadedHeight } =
+			await this.cachedSource;
+
+		// Prefer element-stored intrinsic dimensions as the geometry authority.
+		// The loaded image is only the drawable source.
+		const sourceWidth = this.params.intrinsicWidth ?? loadedWidth;
+		const sourceHeight = this.params.intrinsicHeight ?? loadedHeight;

 		this.renderVisual({
 			renderer,
 			source,
-			sourceWidth: width,
-			sourceHeight: height,
+			sourceWidth,
+			sourceHeight,
 			timelineTime: time,
 		});
 	}
@@ -1,12 +1,8 @@
 import type { CanvasRenderer } from "../canvas-renderer";
 import { createOffscreenCanvas } from "../canvas-utils";
 import { BaseNode } from "./base-node";
-import type { TextElement } from "@/types/timeline";
+import type { TextElement } from "@/lib/timeline";
 import {
-	DEFAULT_TEXT_BACKGROUND,
-	DEFAULT_TEXT_ELEMENT,
-	DEFAULT_LINE_HEIGHT,
-	FONT_SIZE_SCALE_REFERENCE,
 	CORNER_RADIUS_MAX,
 	CORNER_RADIUS_MIN,
 } from "@/constants/text-constants";
@@ -14,34 +10,20 @@ import {
 	getMetricAscent,
 	getMetricDescent,
 	getTextBackgroundRect,
-	measureTextBlock,
+	setCanvasLetterSpacing,
 } from "@/lib/text/layout";
+import { measureTextElement } from "@/lib/text/measure-element";
 import {
 	getElementLocalTime,
 	resolveColorAtTime,
-	resolveNumberAtTime,
 	resolveOpacityAtTime,
 	resolveTransformAtTime,
 } from "@/lib/animation";
 import { resolveEffectParamsAtTime } from "@/lib/animation/effect-param-channel";
-import { getEffect } from "@/lib/effects";
-import { webglEffectRenderer } from "../webgl-effect-renderer";
+import { effectsRegistry, resolveEffectPasses } from "@/lib/effects";
+import { webglEffectRenderer } from "../webgl/webgl-effect-renderer";
 import { clamp } from "@/utils/math";

-function scaleFontSize({
-	fontSize,
-	canvasHeight,
-}: {
-	fontSize: number;
-	canvasHeight: number;
-}): number {
-	return fontSize * (canvasHeight / FONT_SIZE_SCALE_REFERENCE);
-}
-
-function quoteFontFamily({ fontFamily }: { fontFamily: string }): string {
-	return `"${fontFamily.replace(/"/g, '\\"')}"`;
-}
-
 const TEXT_DECORATION_THICKNESS_RATIO = 0.07;
 const STRIKETHROUGH_VERTICAL_RATIO = 0.35;

@@ -64,9 +46,15 @@ function drawTextDecoration({
 }): void {
 	if (textDecoration === "none" || !textDecoration) return;

-	const thickness = Math.max(1, scaledFontSize * TEXT_DECORATION_THICKNESS_RATIO);
+	const thickness = Math.max(
+		1,
+		scaledFontSize * TEXT_DECORATION_THICKNESS_RATIO,
+	);
 	const ascent = getMetricAscent({ metrics, fallbackFontSize: scaledFontSize });
-	const descent = getMetricDescent({ metrics, fallbackFontSize: scaledFontSize });
+	const descent = getMetricDescent({
+		metrics,
+		fallbackFontSize: scaledFontSize,
+	});

 	let xStart = -lineWidth / 2;
 	if (textAlign === "left") xStart = 0;
@@ -121,19 +109,6 @@ export class TextNode extends BaseNode<TextNodeParams> {
 		const x = transform.position.x + this.params.canvasCenter.x;
 		const y = transform.position.y + this.params.canvasCenter.y;

-		const fontWeight = this.params.fontWeight === "bold" ? "bold" : "normal";
-		const fontStyle = this.params.fontStyle === "italic" ? "italic" : "normal";
-		const scaledFontSize = scaleFontSize({
-			fontSize: this.params.fontSize,
-			canvasHeight: this.params.canvasHeight,
-		});
-		const fontFamily = quoteFontFamily({ fontFamily: this.params.fontFamily });
-		const fontString = `${fontStyle} ${fontWeight} ${scaledFontSize}px ${fontFamily}, sans-serif`;
-		const letterSpacing = this.params.letterSpacing ?? 0;
-		const lineHeight = this.params.lineHeight ?? DEFAULT_LINE_HEIGHT;
-		const lines = this.params.content.split("\n");
-		const lineHeightPx = scaledFontSize * lineHeight;
-		const fontSizeRatio = this.params.fontSize / DEFAULT_TEXT_ELEMENT.fontSize;
 		const baseline = this.params.textBaseline ?? "middle";
 		const blendMode = (
 			this.params.blendMode && this.params.blendMode !== "normal"
@@ -141,73 +116,49 @@ export class TextNode extends BaseNode<TextNodeParams> {
 				: "source-over"
 		) as GlobalCompositeOperation;

-	renderer.context.save();
-		renderer.context.font = fontString;
-		renderer.context.textBaseline = baseline;
-		if ("letterSpacing" in renderer.context) {
-			(renderer.context as CanvasRenderingContext2D & { letterSpacing: string }).letterSpacing = `${letterSpacing}px`;
-		}
-		const lineMetrics = lines.map((line) => renderer.context.measureText(line));
-		renderer.context.restore();
+		const {
+			scaledFontSize,
+			fontString,
+			letterSpacing,
+			lineHeightPx,
+			lines,
+			lineMetrics,
+			block,
+			fontSizeRatio,
+			resolvedBackground,
+		} = measureTextElement({
+			element: this.params,
+			canvasHeight: this.params.canvasHeight,
+			localTime,
+			ctx: renderer.context,
+		});

 		const lineCount = lines.length;
-		const block = measureTextBlock({ lineMetrics, lineHeightPx, fallbackFontSize: scaledFontSize });

-	const textColor = resolveColorAtTime({
+		const textColor = resolveColorAtTime({
 			baseColor: this.params.color,
 			animations: this.params.animations,
 			propertyPath: "color",
 			localTime,
 		});
-		const bg = this.params.background;
-		const resolvedBackground = {
-			...bg,
+		const resolvedBackgroundWithColor = {
+			...resolvedBackground,
 			color: resolveColorAtTime({
-				baseColor: bg.color,
+				baseColor: this.params.background.color,
 				animations: this.params.animations,
 				propertyPath: "background.color",
 				localTime,
 			}),
-			paddingX: resolveNumberAtTime({
-				baseValue: bg.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
-				animations: this.params.animations,
-				propertyPath: "background.paddingX",
-				localTime,
-			}),
-			paddingY: resolveNumberAtTime({
-				baseValue: bg.paddingY ?? DEFAULT_TEXT_BACKGROUND.paddingY,
-				animations: this.params.animations,
-				propertyPath: "background.paddingY",
-				localTime,
-			}),
-			offsetX: resolveNumberAtTime({
-				baseValue: bg.offsetX ?? DEFAULT_TEXT_BACKGROUND.offsetX,
-				animations: this.params.animations,
-				propertyPath: "background.offsetX",
-				localTime,
-			}),
-			offsetY: resolveNumberAtTime({
-				baseValue: bg.offsetY ?? DEFAULT_TEXT_BACKGROUND.offsetY,
-				animations: this.params.animations,
-				propertyPath: "background.offsetY",
-				localTime,
-			}),
-			cornerRadius: resolveNumberAtTime({
-				baseValue: bg.cornerRadius ?? CORNER_RADIUS_MIN,
-				animations: this.params.animations,
-				propertyPath: "background.cornerRadius",
-				localTime,
-			}),
 		};

-	const drawContent = (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => {
+		const drawContent = (
+			ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+		) => {
 			ctx.font = fontString;
 			ctx.textAlign = this.params.textAlign;
 			ctx.textBaseline = baseline;
 			ctx.fillStyle = textColor;
-			if ("letterSpacing" in ctx) {
-				(ctx as CanvasRenderingContext2D & { letterSpacing: string }).letterSpacing = `${letterSpacing}px`;
-			}
+			setCanvasLetterSpacing({ ctx, letterSpacingPx: letterSpacing });

 			if (
 				this.params.background.enabled &&
@@ -218,17 +169,29 @@ export class TextNode extends BaseNode<TextNodeParams> {
 				const backgroundRect = getTextBackgroundRect({
 					textAlign: this.params.textAlign,
 					block,
-					background: resolvedBackground,
+					background: resolvedBackgroundWithColor,
 					fontSizeRatio,
 				});
 				if (backgroundRect) {
-					const p = clamp({ value: resolvedBackground.cornerRadius, min: CORNER_RADIUS_MIN, max: CORNER_RADIUS_MAX }) / 100;
-					const radius = Math.min(backgroundRect.width, backgroundRect.height) / 2 * p;
-				ctx.fillStyle = resolvedBackground.color;
-				ctx.beginPath();
-				ctx.roundRect(backgroundRect.left, backgroundRect.top, backgroundRect.width, backgroundRect.height, radius);
-				ctx.fill();
-				ctx.fillStyle = textColor;
+					const p =
+						clamp({
+							value: resolvedBackgroundWithColor.cornerRadius,
+							min: CORNER_RADIUS_MIN,
+							max: CORNER_RADIUS_MAX,
+						}) / 100;
+					const radius =
+						(Math.min(backgroundRect.width, backgroundRect.height) / 2) * p;
+					ctx.fillStyle = resolvedBackgroundWithColor.color;
+					ctx.beginPath();
+					ctx.roundRect(
+						backgroundRect.left,
+						backgroundRect.top,
+						backgroundRect.width,
+						backgroundRect.height,
+						radius,
+					);
+					ctx.fill();
+					ctx.fillStyle = textColor;
 				}
 			}

@@ -247,15 +210,18 @@ export class TextNode extends BaseNode<TextNodeParams> {
 			}
 		};

-		const applyTransform = (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => {
+		const applyTransform = (
+			ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+		) => {
 			ctx.translate(x, y);
-			ctx.scale(transform.scale, transform.scale);
+			ctx.scale(transform.scaleX, transform.scaleY);
 			if (transform.rotate) {
 				ctx.rotate((transform.rotate * Math.PI) / 180);
 			}
 		};

-		const enabledEffects = this.params.effects?.filter((effect) => effect.enabled) ?? [];
+		const enabledEffects =
+			this.params.effects?.filter((effect) => effect.enabled) ?? [];

 		if (enabledEffects.length === 0) {
 			renderer.context.save();
@@ -269,11 +235,16 @@ export class TextNode extends BaseNode<TextNodeParams> {

 		// Effects path: render text to a same-size offscreen canvas so the blur
 		// can spread into the surrounding transparent area without hard clipping.
-		const offscreen = createOffscreenCanvas({ width: renderer.width, height: renderer.height });
-		const offscreenCtx = offscreen.getContext("2d") as OffscreenCanvasRenderingContext2D | null;
+		const offscreen = createOffscreenCanvas({
+			width: renderer.width,
+			height: renderer.height,
+		});
+		const offscreenCtx = offscreen.getContext(
+			"2d",
+		) as OffscreenCanvasRenderingContext2D | null;

 		if (!offscreenCtx) {
-		renderer.context.save();
+			renderer.context.save();
 			applyTransform(renderer.context);
 			renderer.context.globalCompositeOperation = blendMode;
 			renderer.context.globalAlpha = opacity;
@@ -294,15 +265,13 @@ export class TextNode extends BaseNode<TextNodeParams> {
 				animations: this.params.animations,
 				localTime,
 			});
-			const definition = getEffect({ effectType: effect.type });
-			const passes = definition.renderer.passes.map((pass) => ({
-				fragmentShader: pass.fragmentShader,
-				uniforms: pass.uniforms({
-					effectParams: resolvedParams,
-					width: renderer.width,
-					height: renderer.height,
-				}),
-			}));
+			const definition = effectsRegistry.get(effect.type);
+			const passes = resolveEffectPasses({
+				definition,
+				effectParams: resolvedParams,
+				width: renderer.width,
+				height: renderer.height,
+			});
 			currentSource = webglEffectRenderer.applyEffect({
 				source: currentSource,
 				width: renderer.width,
@@ -17,6 +17,7 @@ export class VideoNode extends VisualNode<VideoNodeParams> {
 		}

 		const videoTime = this.getSourceLocalTime({ time });
+
 		const frame = await videoCache.getFrameAt({
 			mediaId: this.params.mediaId,
 			file: this.params.file,
@@ -1,10 +1,11 @@
 import type { CanvasRenderer } from "../canvas-renderer";
 import { createOffscreenCanvas } from "../canvas-utils";
 import { BaseNode } from "./base-node";
-import type { Effect } from "@/types/effects";
-import type { BlendMode } from "@/types/rendering";
-import type { Transform } from "@/types/timeline";
-import type { ElementAnimations } from "@/types/animation";
+import type { Effect } from "@/lib/effects/types";
+import type { Mask } from "@/lib/masks/types";
+import type { BlendMode, Transform } from "@/lib/rendering";
+import type { ElementAnimations } from "@/lib/animation/types";
+import type { RetimeConfig } from "@/lib/timeline";
 import {
 	getElementLocalTime,
 	resolveOpacityAtTime,
@@ -12,26 +13,38 @@ import {
 } from "@/lib/animation";
 import { resolveEffectParamsAtTime } from "@/lib/animation/effect-param-channel";
 import { TIME_EPSILON_SECONDS } from "@/constants/animation-constants";
-import { getEffect } from "@/lib/effects";
-import { webglEffectRenderer } from "../webgl-effect-renderer";
+import { effectsRegistry, resolveEffectPasses } from "@/lib/effects";
+import { masksRegistry } from "@/lib/masks";
+import { getSourceTimeAtClipTime } from "@/lib/retime";
+import { webglEffectRenderer } from "../webgl/webgl-effect-renderer";
+import { applyMaskFeather } from "../mask-feather";

 export interface VisualNodeParams {
 	duration: number;
 	timeOffset: number;
 	trimStart: number;
 	trimEnd: number;
+	retime?: RetimeConfig;
 	transform: Transform;
 	animations?: ElementAnimations;
 	opacity: number;
 	blendMode?: BlendMode;
 	effects?: Effect[];
+	masks?: Mask[];
 }

 export abstract class VisualNode<
 	Params extends VisualNodeParams = VisualNodeParams,
 > extends BaseNode<Params> {
 	protected getSourceLocalTime({ time }: { time: number }): number {
-		return time - this.params.timeOffset + this.params.trimStart;
+		const clipTime = time - this.params.timeOffset;
+		return (
+			this.params.trimStart +
+			getSourceTimeAtClipTime({
+				clipTime,
+				retime: this.params.retime,
+			})
+		);
 	}

 	protected getAnimationLocalTime({ time }: { time: number }): number {
@@ -43,10 +56,10 @@ export abstract class VisualNode<
 	}

 	protected isInRange({ time }: { time: number }): boolean {
-		const localTime = this.getSourceLocalTime({ time });
+		const localTime = time - this.params.timeOffset;
 		return (
-			localTime >= this.params.trimStart - TIME_EPSILON_SECONDS &&
-			localTime < this.params.trimStart + this.params.duration
+			localTime >= -TIME_EPSILON_SECONDS &&
+			localTime < this.params.duration
 		);
 	}

@@ -65,7 +78,9 @@ export abstract class VisualNode<
 	}): void {
 		renderer.context.save();

-		const animationLocalTime = this.getAnimationLocalTime({ time: timelineTime });
+		const animationLocalTime = this.getAnimationLocalTime({
+			time: timelineTime,
+		});
 		const transform = resolveTransformAtTime({
 			baseTransform: this.params.transform,
 			animations: this.params.animations,
@@ -80,10 +95,12 @@ export abstract class VisualNode<
 			renderer.width / sourceWidth,
 			renderer.height / sourceHeight,
 		);
-		const scaledWidth = sourceWidth * containScale * transform.scale;
-		const scaledHeight = sourceHeight * containScale * transform.scale;
-		const x = renderer.width / 2 + transform.position.x - scaledWidth / 2;
-		const y = renderer.height / 2 + transform.position.y - scaledHeight / 2;
+		const scaledWidth = sourceWidth * containScale * transform.scaleX;
+		const scaledHeight = sourceHeight * containScale * transform.scaleY;
+		const absWidth = Math.abs(scaledWidth);
+		const absHeight = Math.abs(scaledHeight);
+		const x = renderer.width / 2 + transform.position.x - absWidth / 2;
+		const y = renderer.height / 2 + transform.position.y - absHeight / 2;

 		renderer.context.globalCompositeOperation = (
 			this.params.blendMode && this.params.blendMode !== "normal"
@@ -92,71 +109,187 @@ export abstract class VisualNode<
 		) as GlobalCompositeOperation;
 		renderer.context.globalAlpha = opacity;

-		if (transform.rotate !== 0) {
-			const centerX = x + scaledWidth / 2;
-			const centerY = y + scaledHeight / 2;
+		const flipX = scaledWidth < 0 ? -1 : 1;
+		const flipY = scaledHeight < 0 ? -1 : 1;
+		const needsTransform = transform.rotate !== 0 || flipX !== 1 || flipY !== 1;
+
+		if (needsTransform) {
+			const centerX = x + absWidth / 2;
+			const centerY = y + absHeight / 2;
 			renderer.context.translate(centerX, centerY);
 			renderer.context.rotate((transform.rotate * Math.PI) / 180);
+			renderer.context.scale(flipX, flipY);
 			renderer.context.translate(-centerX, -centerY);
 		}

 		const enabledEffects =
 			this.params.effects?.filter((effect) => effect.enabled) ?? [];
+		const activeMasks = this.params.masks ?? [];

-		if (enabledEffects.length === 0) {
-			renderer.context.drawImage(source, x, y, scaledWidth, scaledHeight);
+		if (activeMasks.length === 0 && enabledEffects.length === 0) {
+			renderer.context.drawImage(source, x, y, absWidth, absHeight);
+			renderer.context.restore();
+			return;
+		}
+
+		const currentResult =
+			enabledEffects.length > 0
+				? this.applyEffects({
+						source,
+						effects: enabledEffects,
+						width: absWidth,
+						height: absHeight,
+						animationLocalTime,
+					})
+				: source;
+
+		if (activeMasks.length === 0) {
+			renderer.context.drawImage(currentResult, x, y, absWidth, absHeight);
 			renderer.context.restore();
 			return;
 		}

 		const elementCanvas = createOffscreenCanvas({
-			width: Math.round(scaledWidth),
-			height: Math.round(scaledHeight),
+			width: Math.round(absWidth),
+			height: Math.round(absHeight),
 		});
 		const elementCtx = elementCanvas.getContext("2d") as
 			| CanvasRenderingContext2D
 			| OffscreenCanvasRenderingContext2D
 			| null;
 		if (!elementCtx) {
-			renderer.context.drawImage(source, x, y, scaledWidth, scaledHeight);
+			renderer.context.drawImage(currentResult, x, y, absWidth, absHeight);
 			renderer.context.restore();
 			return;
 		}

-		elementCtx.drawImage(source, 0, 0, scaledWidth, scaledHeight);
+		elementCtx.drawImage(currentResult, 0, 0, absWidth, absHeight);

-		let currentResult: CanvasImageSource = elementCanvas;
+		for (const mask of activeMasks) {
+			this.applyMask({
+				mask,
+				elementCtx,
+				scaledWidth: absWidth,
+				scaledHeight: absHeight,
+			});
+		}

-		for (const effect of enabledEffects) {
+		renderer.context.drawImage(elementCanvas, x, y, absWidth, absHeight);
+		renderer.context.restore();
+	}
+
+	private applyEffects({
+		source,
+		effects,
+		width,
+		height,
+		animationLocalTime,
+	}: {
+		source: CanvasImageSource;
+		effects: Effect[];
+		width: number;
+		height: number;
+		animationLocalTime: number;
+	}): CanvasImageSource {
+		let current: CanvasImageSource = source;
+		for (const effect of effects) {
 			const resolvedParams = resolveEffectParamsAtTime({
 				effect,
 				animations: this.params.animations,
 				localTime: animationLocalTime,
 			});
-			const definition = getEffect({ effectType: effect.type });
-			const passes = definition.renderer.passes.map((pass) => ({
-				fragmentShader: pass.fragmentShader,
-				uniforms: pass.uniforms({
-					effectParams: resolvedParams,
-					width: scaledWidth,
-					height: scaledHeight,
-				}),
-			}));
-			currentResult = webglEffectRenderer.applyEffect({
-				source: currentResult,
-				width: Math.round(scaledWidth),
-				height: Math.round(scaledHeight),
+			const definition = effectsRegistry.get(effect.type);
+			const passes = resolveEffectPasses({
+				definition,
+				effectParams: resolvedParams,
+				width,
+				height,
+			});
+			current = webglEffectRenderer.applyEffect({
+				source: current,
+				width: Math.round(width),
+				height: Math.round(height),
 				passes,
 			});
 		}
+		return current;
+	}

-		renderer.context.drawImage(
-			currentResult,
-			x,
-			y,
-			scaledWidth,
-			scaledHeight,
-		);
-		renderer.context.restore();
+	private applyMask({
+		mask,
+		elementCtx,
+		scaledWidth,
+		scaledHeight,
+	}: {
+		mask: Mask;
+		elementCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+		scaledWidth: number;
+		scaledHeight: number;
+	}): void {
+		const definition = masksRegistry.get(mask.type);
+		const { feather, inverted } = mask.params;
+
+		const maskCanvas = createOffscreenCanvas({
+			width: Math.round(scaledWidth),
+			height: Math.round(scaledHeight),
+		});
+		const maskCtx = maskCanvas.getContext("2d") as
+			| CanvasRenderingContext2D
+			| OffscreenCanvasRenderingContext2D
+			| null;
+		if (!maskCtx) return;
+
+		maskCtx.clearRect(0, 0, scaledWidth, scaledHeight);
+
+		let maskResult: CanvasImageSource = maskCanvas;
+		let path: Path2D | null = null;
+
+		if (feather > 0 && definition.renderer.renderMask) {
+			// Bypasses JFA — avoids the two-sided distance artifact where strips
+			// near the canvas edge appear semi-transparent.
+			definition.renderer.renderMask({
+				resolvedParams: mask.params,
+				ctx: maskCtx,
+				width: Math.round(scaledWidth),
+				height: Math.round(scaledHeight),
+				feather,
+			});
+		} else {
+			path = definition.renderer.buildPath({
+				resolvedParams: mask.params,
+				width: scaledWidth,
+				height: scaledHeight,
+			});
+			maskCtx.fillStyle = "white";
+			maskCtx.fill(path);
+
+			if (feather > 0) {
+				maskResult = applyMaskFeather({
+					maskCanvas,
+					width: Math.round(scaledWidth),
+					height: Math.round(scaledHeight),
+					feather,
+				});
+			}
+		}
+
+		elementCtx.globalCompositeOperation = inverted
+			? "destination-out"
+			: "destination-in";
+		elementCtx.drawImage(maskResult, 0, 0, scaledWidth, scaledHeight);
+		elementCtx.globalCompositeOperation = "source-over";
+
+		const strokePath =
+			definition.renderer.buildStrokePath?.({
+				resolvedParams: mask.params,
+				width: scaledWidth,
+				height: scaledHeight,
+			}) ?? path;
+
+		if (mask.params.strokeWidth > 0 && strokePath) {
+			elementCtx.strokeStyle = mask.params.strokeColor;
+			elementCtx.lineWidth = mask.params.strokeWidth;
+			elementCtx.stroke(strokePath);
+		}
 	}
 }
@@ -1,26 +1,22 @@
-import type { TimelineTrack } from "@/types/timeline";
-import type { MediaAsset } from "@/types/assets";
+import type { TimelineTrack } from "@/lib/timeline";
+import type { MediaAsset } from "@/lib/media/types";
 import { RootNode } from "./nodes/root-node";
 import { VideoNode } from "./nodes/video-node";
 import { ImageNode } from "./nodes/image-node";
 import { TextNode } from "./nodes/text-node";
 import { StickerNode } from "./nodes/sticker-node";
+import { GraphicNode } from "./nodes/graphic-node";
 import { ColorNode } from "./nodes/color-node";
-import { CompositeEffectNode } from "./nodes/composite-effect-node";
+import { BlurBackgroundNode } from "./nodes/blur-background-node";
 import { EffectLayerNode } from "./nodes/effect-layer-node";
 import type { BaseNode } from "./nodes/base-node";
-import type { TBackground, TCanvasSize } from "@/types/project";
+import type { TBackground, TCanvasSize } from "@/lib/project/types";
 import { DEFAULT_BLUR_INTENSITY } from "@/constants/project-constants";
 import { isMainTrack } from "@/lib/timeline";

 const PREVIEW_MAX_IMAGE_SIZE = 2048;
-const BLUR_BACKGROUND_ZOOM_SCALE = 1.4;

-function getVisibleSortedElements({
-	track,
-}: {
-	track: TimelineTrack;
-}) {
+function getVisibleSortedElements({ track }: { track: TimelineTrack }) {
 	return track.elements
 		.filter((element) => !("hidden" in element && element.hidden))
 		.slice()
@@ -65,7 +61,7 @@ function buildTrackNodes({
 					continue;
 				}

-				if (mediaAsset.type === "video") {
+				if (element.type === "video" && mediaAsset.type === "video") {
 					nodes.push(
 						new VideoNode({
 							mediaId: mediaAsset.id,
@@ -75,15 +71,17 @@ function buildTrackNodes({
 							timeOffset: element.startTime,
 							trimStart: element.trimStart,
 							trimEnd: element.trimEnd,
+							retime: element.retime,
 							transform: element.transform,
 							animations: element.animations,
 							opacity: element.opacity,
 							blendMode: element.blendMode,
 							effects: element.effects,
+							masks: element.masks,
 						}),
 					);
 				}
-				if (mediaAsset.type === "image") {
+				if (element.type === "image" && mediaAsset.type === "image") {
 					nodes.push(
 						new ImageNode({
 							url: mediaAsset.url,
@@ -96,6 +94,7 @@ function buildTrackNodes({
 							opacity: element.opacity,
 							blendMode: element.blendMode,
 							effects: element.effects,
+							masks: element.masks,
 							...(isPreview && {
 								maxSourceSize: PREVIEW_MAX_IMAGE_SIZE,
 							}),
@@ -120,6 +119,8 @@ function buildTrackNodes({
 				nodes.push(
 					new StickerNode({
 						stickerId: element.stickerId,
+						intrinsicWidth: element.intrinsicWidth,
+						intrinsicHeight: element.intrinsicHeight,
 						duration: element.duration,
 						timeOffset: element.startTime,
 						trimStart: element.trimStart,
@@ -132,12 +133,80 @@ function buildTrackNodes({
 					}),
 				);
 			}
+
+			if (element.type === "graphic") {
+				nodes.push(
+					new GraphicNode({
+						definitionId: element.definitionId,
+						params: element.params,
+						duration: element.duration,
+						timeOffset: element.startTime,
+						trimStart: element.trimStart,
+						trimEnd: element.trimEnd,
+						transform: element.transform,
+						animations: element.animations,
+						opacity: element.opacity,
+						blendMode: element.blendMode,
+						effects: element.effects,
+						masks: element.masks,
+					}),
+				);
+			}
 		}
 	}

 	return nodes;
 }

+function buildBlurBackgroundNodes({
+	track,
+	mediaMap,
+	blurIntensity,
+}: {
+	track: TimelineTrack | undefined;
+	mediaMap: Map<string, MediaAsset>;
+	blurIntensity: number;
+}): BaseNode[] {
+	if (!track) {
+		return [];
+	}
+
+	const nodes: BaseNode[] = [];
+	const elements = getVisibleSortedElements({ track });
+
+	for (const element of elements) {
+		if (element.type !== "video" && element.type !== "image") {
+			continue;
+		}
+
+		const mediaAsset = mediaMap.get(element.mediaId);
+		if (
+			!mediaAsset?.file ||
+			!mediaAsset?.url ||
+			(mediaAsset.type !== "video" && mediaAsset.type !== "image")
+		) {
+			continue;
+		}
+
+		nodes.push(
+			new BlurBackgroundNode({
+				mediaId: mediaAsset.id,
+				url: mediaAsset.url,
+				file: mediaAsset.file,
+				mediaType: mediaAsset.type,
+				duration: element.duration,
+				timeOffset: element.startTime,
+				trimStart: element.trimStart,
+				trimEnd: element.trimEnd,
+				retime: element.type === "video" ? element.retime : undefined,
+				blurIntensity,
+			}),
+		);
+	}
+
+	return nodes;
+}
+
 export type BuildSceneParams = {
 	canvasSize: TCanvasSize;
 	tracks: TimelineTrack[];
@@ -168,6 +237,9 @@ export function buildScene({
 	];

 	const orderedTracksBottomToTop = orderedTracksTopToBottom.slice().reverse();
+	const mainTrack = orderedTracksBottomToTop.find((track) =>
+		isMainTrack(track),
+	);

 	const allNodes = buildTrackNodes({
 		tracks: orderedTracksBottomToTop,
@@ -177,20 +249,18 @@ export function buildScene({
 	});

 	if (background.type === "blur") {
-		rootNode.add(
-			new CompositeEffectNode({
-				contentNodes: allNodes.filter(
-					(node) => !(node instanceof EffectLayerNode),
-				),
-				effectType: "blur",
-				effectParams: {
-					intensity:
-						background.blurIntensity ?? DEFAULT_BLUR_INTENSITY,
-				},
-				scale: BLUR_BACKGROUND_ZOOM_SCALE,
-			}),
-		);
-	} else if (background.type === "color" && background.color !== "transparent") {
+		const blurNodes = buildBlurBackgroundNodes({
+			track: mainTrack,
+			mediaMap,
+			blurIntensity: background.blurIntensity ?? DEFAULT_BLUR_INTENSITY,
+		});
+		for (const node of blurNodes) {
+			rootNode.add(node);
+		}
+	} else if (
+		background.type === "color" &&
+		background.color !== "transparent"
+	) {
 		rootNode.add(new ColorNode({ color: background.color }));
 	}

@@ -13,7 +13,7 @@ import {
 	QUALITY_VERY_HIGH,
 } from "mediabunny";
 import type { RootNode } from "./nodes/root-node";
-import type { ExportFormat, ExportQuality } from "@/types/export";
+import type { ExportFormat, ExportQuality } from "@/lib/export";
 import { CanvasRenderer } from "./canvas-renderer";

 type ExportParams = {
@@ -1,73 +0,0 @@
-import { createOffscreenCanvas } from "./canvas-utils";
-import { applyMultiPassEffect } from "./webgl-utils";
-import type { EffectPassData } from "./webgl-utils";
-
-export interface ApplyEffectParams {
-	source: CanvasImageSource;
-	width: number;
-	height: number;
-	passes: EffectPassData[];
-}
-
-let gl: WebGLRenderingContext | null = null;
-let canvas: OffscreenCanvas | HTMLCanvasElement | null = null;
-const programCache = new Map<string, WebGLProgram>();
-
-function getOrCreateCanvas({
-	width,
-	height,
-}: {
-	width: number;
-	height: number;
-}): OffscreenCanvas | HTMLCanvasElement {
-	if (!canvas) {
-		canvas = createOffscreenCanvas({ width, height });
-		gl = canvas.getContext("webgl", {
-			premultipliedAlpha: false,
-		}) as WebGLRenderingContext | null;
-		if (!gl) {
-			throw new Error("WebGL not supported");
-		}
-	}
-	if (canvas.width !== width || canvas.height !== height) {
-		canvas.width = width;
-		canvas.height = height;
-	}
-	return canvas;
-}
-
-function applyEffect({
-	source,
-	width,
-	height,
-	passes,
-}: ApplyEffectParams): OffscreenCanvas | HTMLCanvasElement {
-	const targetCanvas = getOrCreateCanvas({ width, height });
-	const context = gl;
-	if (!context) {
-		throw new Error("WebGL context not initialized");
-	}
-
-	applyMultiPassEffect({
-		context,
-		source,
-		width,
-		height,
-		passes,
-		programCache,
-	});
-
-	const outputCanvas = createOffscreenCanvas({ width, height });
-	const outputCtx = outputCanvas.getContext("2d") as
-		| CanvasRenderingContext2D
-		| OffscreenCanvasRenderingContext2D
-		| null;
-	if (outputCtx) {
-		outputCtx.drawImage(targetCanvas, 0, 0, width, height);
-	}
-	return outputCanvas;
-}
-
-export const webglEffectRenderer = {
-	applyEffect,
-};
@@ -0,0 +1,194 @@
+import jfaInitShader from "@/lib/shaders/jfa-init.frag.glsl";
+import jfaStepShader from "@/lib/shaders/jfa-step.frag.glsl";
+import {
+	compileProgram,
+	createFramebufferTexture,
+	setUniforms,
+	drawFullscreenQuad,
+} from "./webgl-utils";
+
+interface FBPair {
+	texture: WebGLTexture;
+	framebuffer: WebGLFramebuffer;
+}
+
+function runPass({
+	context,
+	program,
+	inputTexture,
+	target,
+	width,
+	height,
+	uniforms,
+	extraBindings,
+}: {
+	context: WebGLRenderingContext;
+	program: WebGLProgram;
+	inputTexture: WebGLTexture;
+	target: WebGLFramebuffer | null;
+	width: number;
+	height: number;
+	uniforms: Record<string, number | number[]>;
+	extraBindings?: Array<{ unit: number; texture: WebGLTexture; name: string }>;
+}): void {
+	context.bindFramebuffer(context.FRAMEBUFFER, target);
+	// biome-ignore lint/correctness/useHookAtTopLevel: WebGL API method, not a React hook
+	context.useProgram(program);
+
+	context.activeTexture(context.TEXTURE0);
+	context.bindTexture(context.TEXTURE_2D, inputTexture);
+	const uTexLoc = context.getUniformLocation(program, "u_texture");
+	if (uTexLoc) context.uniform1i(uTexLoc, 0);
+
+	if (extraBindings) {
+		for (const binding of extraBindings) {
+			context.activeTexture(context.TEXTURE0 + binding.unit);
+			context.bindTexture(context.TEXTURE_2D, binding.texture);
+			const loc = context.getUniformLocation(program, binding.name);
+			if (loc) context.uniform1i(loc, binding.unit);
+		}
+	}
+
+	setUniforms({
+		context,
+		program,
+		uniforms: { ...uniforms, u_resolution: [width, height] },
+	});
+	drawFullscreenQuad({ context, program, width, height });
+}
+
+function runJFA({
+	context,
+	programCache,
+	sourceTexture,
+	width,
+	height,
+	isInverted,
+}: {
+	context: WebGLRenderingContext;
+	programCache: Map<string, WebGLProgram>;
+	sourceTexture: WebGLTexture;
+	width: number;
+	height: number;
+	isInverted: boolean;
+}): {
+	resultTexture: WebGLTexture;
+	resultFB: WebGLFramebuffer;
+	tempFBs: FBPair[];
+} {
+	const numSteps = Math.ceil(Math.log2(Math.max(width, height)));
+
+	const fbA = createFramebufferTexture({ context, width, height });
+	const fbB = createFramebufferTexture({ context, width, height });
+
+	const initProgram = compileProgram({
+		context,
+		fragmentShaderSource: jfaInitShader,
+		programCache,
+	});
+	runPass({
+		context,
+		program: initProgram,
+		inputTexture: sourceTexture,
+		target: fbA.framebuffer,
+		width,
+		height,
+		uniforms: { u_invert: isInverted ? 1.0 : 0.0 },
+	});
+
+	const stepProgram = compileProgram({
+		context,
+		fragmentShaderSource: jfaStepShader,
+		programCache,
+	});
+
+	let readFB = fbA;
+	let writeFB = fbB;
+
+	for (let i = numSteps - 1; i >= 0; i--) {
+		const stepSize = 2 ** i;
+		runPass({
+			context,
+			program: stepProgram,
+			inputTexture: readFB.texture,
+			target: writeFB.framebuffer,
+			width,
+			height,
+			uniforms: { u_step_size: stepSize },
+		});
+		const tmp = readFB;
+		readFB = writeFB;
+		writeFB = tmp;
+	}
+
+	return {
+		resultTexture: readFB.texture,
+		resultFB: readFB.framebuffer,
+		tempFBs: [writeFB],
+	};
+}
+
+function cleanupJFAResult({
+	context,
+	result,
+}: {
+	context: WebGLRenderingContext;
+	result: {
+		resultTexture: WebGLTexture;
+		resultFB: WebGLFramebuffer;
+		tempFBs: FBPair[];
+	};
+}): void {
+	context.deleteTexture(result.resultTexture);
+	context.deleteFramebuffer(result.resultFB);
+	for (const fb of result.tempFBs) {
+		context.deleteTexture(fb.texture);
+		context.deleteFramebuffer(fb.framebuffer);
+	}
+}
+
+export { runPass };
+
+export function computeSignedDistanceField({
+	context,
+	programCache,
+	sourceTexture,
+	width,
+	height,
+}: {
+	context: WebGLRenderingContext;
+	programCache: Map<string, WebGLProgram>;
+	sourceTexture: WebGLTexture;
+	width: number;
+	height: number;
+}): {
+	insideTexture: WebGLTexture;
+	outsideTexture: WebGLTexture;
+	cleanup: () => void;
+} {
+	const inside = runJFA({
+		context,
+		programCache,
+		sourceTexture,
+		width,
+		height,
+		isInverted: false,
+	});
+	const outside = runJFA({
+		context,
+		programCache,
+		sourceTexture,
+		width,
+		height,
+		isInverted: true,
+	});
+
+	return {
+		insideTexture: inside.resultTexture,
+		outsideTexture: outside.resultTexture,
+		cleanup: () => {
+			cleanupJFAResult({ context, result: inside });
+			cleanupJFAResult({ context, result: outside });
+		},
+	};
+}
@@ -0,0 +1,49 @@
+import { createOffscreenCanvas } from "../canvas-utils";
+
+let gl: WebGLRenderingContext | null = null;
+let webglCanvas: OffscreenCanvas | HTMLCanvasElement | null = null;
+const programCache = new Map<string, WebGLProgram>();
+
+export function getWebGLContext({
+	width,
+	height,
+}: {
+	width: number;
+	height: number;
+}): {
+	context: WebGLRenderingContext;
+	programCache: Map<string, WebGLProgram>;
+} {
+	if (!webglCanvas) {
+		webglCanvas = createOffscreenCanvas({ width, height });
+		gl = webglCanvas.getContext("webgl", {
+			premultipliedAlpha: false,
+		}) as WebGLRenderingContext | null;
+		if (!gl) throw new Error("WebGL not supported");
+	}
+	if (webglCanvas.width !== width || webglCanvas.height !== height) {
+		webglCanvas.width = width;
+		webglCanvas.height = height;
+	}
+	if (!gl) throw new Error("WebGL context lost");
+	return { context: gl, programCache };
+}
+
+export function readResult({
+	width,
+	height,
+}: {
+	width: number;
+	height: number;
+}): OffscreenCanvas | HTMLCanvasElement {
+	if (!webglCanvas) throw new Error("WebGL canvas not initialized");
+	const outputCanvas = createOffscreenCanvas({ width, height });
+	const outputCtx = outputCanvas.getContext("2d") as
+		| CanvasRenderingContext2D
+		| OffscreenCanvasRenderingContext2D
+		| null;
+	if (outputCtx) {
+		outputCtx.drawImage(webglCanvas, 0, 0, width, height);
+	}
+	return outputCanvas;
+}
@@ -0,0 +1,35 @@
+import { getWebGLContext, readResult } from "./webgl-context";
+import { applyMultiPassEffect } from "./webgl-utils";
+import type { EffectPassData } from "./webgl-utils";
+
+export interface ApplyEffectParams {
+	source: CanvasImageSource;
+	width: number;
+	height: number;
+	passes: EffectPassData[];
+}
+
+function applyEffect({
+	source,
+	width,
+	height,
+	passes,
+}: ApplyEffectParams): CanvasImageSource {
+	if (passes.length === 0) {
+		return source;
+	}
+	const { context, programCache } = getWebGLContext({ width, height });
+	applyMultiPassEffect({
+		context,
+		source,
+		width,
+		height,
+		passes,
+		programCache,
+	});
+	return readResult({ width, height });
+}
+
+export const webglEffectRenderer = {
+	applyEffect,
+};
@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+import { transformProjectV15ToV16 } from "../transformers/v15-to-v16";
+
+describe("V15 to V16 Migration", () => {
+	test("renames sticker tracks to graphic tracks", () => {
+		const result = transformProjectV15ToV16({
+			project: {
+				id: "project-v15",
+				version: 15,
+				metadata: {
+					id: "project-v15",
+					name: "Project",
+					createdAt: "2024-01-01T00:00:00.000Z",
+					updatedAt: "2024-01-01T00:00:00.000Z",
+				},
+				settings: {
+					fps: 30,
+					canvasSize: { width: 1920, height: 1080 },
+					background: { type: "color", color: "#000000" },
+				},
+				currentSceneId: "scene-main",
+				scenes: [
+					{
+						id: "scene-main",
+						name: "Main scene",
+						isMain: true,
+						tracks: [
+							{
+								id: "track-graphic",
+								type: "sticker",
+								name: "Sticker Track",
+								hidden: false,
+								elements: [
+									{
+										id: "sticker-1",
+										type: "sticker",
+										name: "Logo",
+										stickerId: "icons:mdi:home",
+										duration: 5,
+										startTime: 0,
+										trimStart: 0,
+										trimEnd: 0,
+										transform: {
+											scaleX: 1,
+											scaleY: 1,
+											position: { x: 0, y: 0 },
+											rotate: 0,
+										},
+										opacity: 1,
+									},
+								],
+							},
+						],
+						bookmarks: [],
+						createdAt: "2024-01-01T00:00:00.000Z",
+						updatedAt: "2024-01-01T00:00:00.000Z",
+					},
+				],
+			},
+		});
+
+		expect(result.skipped).toBe(false);
+		expect(result.project.version).toBe(16);
+		expect(
+			(result.project.scenes as Array<{ tracks: Array<{ type: string }> }>)[0]
+				.tracks[0].type,
+		).toBe("graphic");
+	});
+
+	test("skips projects already on v16", () => {
+		const result = transformProjectV15ToV16({
+			project: {
+				id: "project-v16",
+				version: 16,
+			},
+		});
+
+		expect(result.skipped).toBe(true);
+		expect(result.reason).toBe("already v16");
+	});
+
+	test("skips projects with no id", () => {
+		const result = transformProjectV15ToV16({
+			project: {
+				version: 15,
+				scenes: [],
+			},
+		});
+
+		expect(result.skipped).toBe(true);
+		expect(result.reason).toBe("no project id");
+	});
+});
@@ -0,0 +1,132 @@
+import { describe, expect, test } from "bun:test";
+import { transformProjectV16ToV17 } from "../transformers/v16-to-v17";
+
+describe("V16 to V17 Migration", () => {
+	test("adds center stroke alignment to masks that do not have it", () => {
+		const result = transformProjectV16ToV17({
+			project: {
+				id: "project-v16",
+				version: 16,
+				metadata: {
+					id: "project-v16",
+					name: "Project",
+					createdAt: "2024-01-01T00:00:00.000Z",
+					updatedAt: "2024-01-01T00:00:00.000Z",
+				},
+				settings: {
+					fps: 30,
+					canvasSize: { width: 1920, height: 1080 },
+					background: { type: "color", color: "#000000" },
+				},
+				currentSceneId: "scene-main",
+				scenes: [
+					{
+						id: "scene-main",
+						name: "Main scene",
+						isMain: true,
+						tracks: [
+							{
+								id: "track-video",
+								type: "video",
+								name: "Video Track",
+								hidden: false,
+								elements: [
+									{
+										id: "video-1",
+										type: "video",
+										name: "Clip",
+										mediaId: "media-1",
+										duration: 5,
+										startTime: 0,
+										trimStart: 0,
+										trimEnd: 0,
+										transform: {
+											scaleX: 1,
+											scaleY: 1,
+											position: { x: 0, y: 0 },
+											rotate: 0,
+										},
+										opacity: 1,
+										masks: [
+											{
+												id: "mask-1",
+												type: "rectangle",
+												params: {
+													feather: 0,
+													inverted: false,
+													strokeColor: "#ffffff",
+													strokeWidth: 8,
+													centerX: 0,
+													centerY: 0,
+													width: 0.6,
+													height: 0.6,
+													rotation: 0,
+													scale: 1,
+												},
+											},
+											{
+												id: "mask-2",
+												type: "ellipse",
+												params: {
+													feather: 0,
+													inverted: false,
+													strokeColor: "#ffffff",
+													strokeWidth: 8,
+													strokeAlign: "outside",
+													centerX: 0,
+													centerY: 0,
+													width: 0.6,
+													height: 0.6,
+													rotation: 0,
+													scale: 1,
+												},
+											},
+										],
+									},
+								],
+							},
+						],
+						bookmarks: [],
+						createdAt: "2024-01-01T00:00:00.000Z",
+						updatedAt: "2024-01-01T00:00:00.000Z",
+					},
+				],
+			},
+		});
+
+		expect(result.skipped).toBe(false);
+		expect(result.project.version).toBe(17);
+
+		const migratedMasks = (
+			((result.project.scenes as Array<{ tracks: Array<{ elements: Array<{ masks: Array<{ params: Record<string, unknown> }> }> }> }>)[0]
+				.tracks[0].elements[0].masks)
+		);
+
+		expect(migratedMasks[0].params.strokeAlign).toBe("center");
+		expect(migratedMasks[1].params.strokeAlign).toBe("outside");
+	});
+
+	test("skips projects already on v17", () => {
+		const result = transformProjectV16ToV17({
+			project: {
+				id: "project-v17",
+				version: 17,
+			},
+		});
+
+		expect(result.skipped).toBe(true);
+		expect(result.reason).toBe("already v17");
+	});
+
+	test("skips projects with no id", () => {
+		const result = transformProjectV16ToV17({
+			project: {
+				version: 16,
+				scenes: [],
+			},
+		});
+
+		expect(result.skipped).toBe(true);
+		expect(result.reason).toBe("no project id");
+	});
+});
@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { transformProjectV18ToV19 } from "../transformers/v18-to-v19";
+
+describe("V18 to V19 Migration", () => {
+	test("adds canvas size mode and empty remembered custom size defaults", () => {
+		const result = transformProjectV18ToV19({
+			project: {
+				id: "project-v18-defaults",
+				version: 18,
+				metadata: {
+					id: "project-v18-defaults",
+					name: "Project",
+					createdAt: "2024-01-01T00:00:00.000Z",
+					updatedAt: "2024-01-01T00:00:00.000Z",
+				},
+				settings: {
+					fps: 30,
+					canvasSize: { width: 1920, height: 1080 },
+					originalCanvasSize: { width: 1920, height: 1080 },
+					background: { type: "color", color: "#000000" },
+				},
+				currentSceneId: "scene-main",
+				scenes: [],
+			},
+		});
+
+		expect(result.skipped).toBe(false);
+		expect(result.project.version).toBe(19);
+		expect(
+			(result.project.settings as Record<string, unknown>).canvasSizeMode,
+		).toBe("preset");
+		expect(
+			(result.project.settings as Record<string, unknown>).lastCustomCanvasSize,
+		).toBeNull();
+		expect(
+			(result.project.settings as Record<string, unknown>).originalCanvasSize,
+		).toEqual({ width: 1920, height: 1080 });
+	});
+
+	test("skips projects already on v19", () => {
+		const result = transformProjectV18ToV19({
+			project: {
+				id: "project-v19",
+				version: 19,
+			},
+		});
+
+		expect(result.skipped).toBe(true);
+		expect(result.reason).toBe("already v19");
+	});
+
+	test("skips projects with no id", () => {
+		const result = transformProjectV18ToV19({
+			project: {
+				version: 18,
+				scenes: [],
+			},
+		});
+
+		expect(result.skipped).toBe(true);
+		expect(result.reason).toBe("no project id");
+	});
+});
@@ -8,10 +8,20 @@ import { V5toV6Migration } from "./v5-to-v6";
 import { V6toV7Migration } from "./v6-to-v7";
 import { V7toV8Migration } from "./v7-to-v8";
 import { V8toV9Migration } from "./v8-to-v9";
+import { V9toV10Migration } from "./v9-to-v10";
+import { V10toV11Migration } from "./v10-to-v11";
+import { V11toV12Migration } from "./v11-to-v12";
+import { V12toV13Migration } from "./v12-to-v13";
+import { V13toV14Migration } from "./v13-to-v14";
+import { V14toV15Migration } from "./v14-to-v15";
+import { V15toV16Migration } from "./v15-to-v16";
+import { V16toV17Migration } from "./v16-to-v17";
+import { V17toV18Migration } from "./v17-to-v18";
+import { V18toV19Migration } from "./v18-to-v19";
 export { runStorageMigrations } from "./runner";
 export type { MigrationProgress } from "./runner";

-export const CURRENT_PROJECT_VERSION = 9;
+export const CURRENT_PROJECT_VERSION = 19;

 export const migrations = [
 	new V0toV1Migration(),
@@ -23,4 +33,14 @@ export const migrations = [
 	new V6toV7Migration(),
 	new V7toV8Migration(),
 	new V8toV9Migration(),
+	new V9toV10Migration(),
+	new V10toV11Migration(),
+	new V11toV12Migration(),
+	new V12toV13Migration(),
+	new V13toV14Migration(),
+	new V14toV15Migration(),
+	new V15toV16Migration(),
+	new V16toV17Migration(),
+	new V17toV18Migration(),
+	new V18toV19Migration(),
 ];
@@ -3,4 +3,5 @@ export { transformProjectV1ToV2 } from "./v1-to-v2";
 export { transformProjectV2ToV3 } from "./v2-to-v3";
 export { transformProjectV3ToV4 } from "./v3-to-v4";
 export { transformProjectV4ToV5 } from "./v4-to-v5";
+export { transformProjectV17ToV18 } from "./v17-to-v18";
 export type { MigrationResult, ProjectRecord } from "./types";
@@ -1,8 +1,17 @@
 import { generateUUID } from "@/utils/id";
-import type { SerializedScene } from "@/services/storage/types";
 import type { MigrationResult, ProjectRecord } from "./types";
 import { isRecord } from "./utils";

+interface V1Scene {
+	id: string;
+	name: string;
+	isMain: boolean;
+	tracks: unknown[];
+	bookmarks: unknown[];
+	createdAt: string;
+	updatedAt: string;
+}
+
 export interface TransformV0ToV1Options {
 	now?: Date;
 }
@@ -25,7 +34,7 @@ export function transformProjectV0ToV1({
 	const sceneCreatedAt = now.toISOString();
 	const sceneUpdatedAt = now.toISOString();

-	const mainScene: SerializedScene = {
+	const mainScene: V1Scene = {
 		id: sceneId,
 		name: "Main scene",
 		isMain: true,
@@ -6,14 +6,6 @@ import {
 } from "@/constants/project-constants";
 import { IndexedDBAdapter } from "@/services/storage/indexeddb-adapter";
 import type { MediaAssetData } from "@/services/storage/types";
-import type {
-	AudioElement,
-	ImageElement,
-	TextElement,
-	TimelineTrack,
-	Transform,
-	VideoElement,
-} from "@/types/timeline";
 import type { MigrationResult, ProjectRecord } from "./types";
 import { getProjectId, isRecord } from "./utils";

@@ -50,6 +42,112 @@ interface LegacyMediaTrack {
 	[key: string]: unknown;
 }

+interface V2Transform {
+	scale: number;
+	position: { x: number; y: number };
+	rotate: number;
+}
+
+interface V2VideoElement {
+	id: string;
+	name: string;
+	type: "video";
+	mediaId: string;
+	muted: boolean;
+	hidden: boolean;
+	transform: V2Transform;
+	opacity: number;
+	duration: number;
+	startTime: number;
+	trimStart: number;
+	trimEnd: number;
+}
+
+interface V2ImageElement {
+	id: string;
+	name: string;
+	type: "image";
+	mediaId: string;
+	duration: number;
+	startTime: number;
+	trimStart: number;
+	trimEnd: number;
+	hidden: boolean;
+	transform: V2Transform;
+	opacity: number;
+}
+
+interface V2TextElement {
+	id: string;
+	name: string;
+	type: "text";
+	content: string;
+	fontSize: number;
+	fontFamily: string;
+	color: string;
+	background: {
+		enabled: boolean;
+		color: string;
+		cornerRadius: number;
+		paddingX: number;
+		paddingY: number;
+		offsetX: number;
+		offsetY: number;
+	};
+	textAlign: "left" | "center" | "right";
+	fontWeight: "normal" | "bold";
+	fontStyle: "normal" | "italic";
+	textDecoration: "none" | "underline" | "line-through";
+	hidden: boolean;
+	transform: V2Transform;
+	opacity: number;
+	duration: number;
+	startTime: number;
+	trimStart: number;
+	trimEnd: number;
+}
+
+interface V2AudioElement {
+	id: string;
+	name: string;
+	type: "audio";
+	sourceType: "upload";
+	mediaId: string;
+	volume: number;
+	duration: number;
+	startTime: number;
+	trimStart: number;
+	trimEnd: number;
+}
+
+interface V2VideoTrack {
+	id: string;
+	name: string;
+	type: "video";
+	elements: (V2VideoElement | V2ImageElement)[];
+	isMain: boolean;
+	muted: boolean;
+	hidden: boolean;
+}
+
+interface V2TextTrack {
+	id: string;
+	name: string;
+	type: "text";
+	elements: V2TextElement[];
+	hidden: boolean;
+}
+
+interface V2AudioTrack {
+	id: string;
+	name: string;
+	type: "audio";
+	elements: V2AudioElement[];
+	muted: boolean;
+}
+
+type V2TimelineTrack = V2VideoTrack | V2TextTrack | V2AudioTrack;
+
 export interface TransformV1ToV2Options {
 	loadMediaAsset?: ({
 		mediaId,
@@ -259,13 +357,13 @@ async function transformTracks({
 	}: {
 		mediaId: string;
 	}) => Promise<MediaAssetData | null>;
-}): Promise<TimelineTrack[]> {
+}): Promise<V2TimelineTrack[]> {
 	if (!Array.isArray(tracks)) {
 		return [];
 	}

 	let isFirstVideoTrackFound = false;
-	const transformedTracks: (TimelineTrack | null)[] = [];
+	const transformedTracks: (V2TimelineTrack | null)[] = [];

 	for (const track of tracks) {
 		if (!isRecord(track)) {
@@ -299,7 +397,7 @@ async function transformTracks({
 	}

 	return transformedTracks.filter(
-		(track): track is TimelineTrack => track !== null,
+		(track): track is V2TimelineTrack => track !== null,
 	);
 }

@@ -315,7 +413,7 @@ async function transformMediaTrack({
 		mediaId: string;
 	}) => Promise<MediaAssetData | null>;
 	isMain: boolean;
-}): Promise<TimelineTrack> {
+}): Promise<V2VideoTrack> {
 	const elements = Array.isArray(track.elements) ? track.elements : [];

 	const transformedElements = await Promise.all(
@@ -338,7 +436,7 @@ async function transformMediaTrack({
 				}
 			}

-			const defaultTransform: Transform = {
+			const defaultTransform: V2Transform = {
 				scale: 1,
 				position: { x: 0, y: 0 },
 				rotate: 0,
@@ -347,7 +445,7 @@ async function transformMediaTrack({
 			const muted = mediaElement.muted === true;

 			if (mediaType === "image") {
-				const imageElement: ImageElement = {
+				const imageElement: V2ImageElement = {
 					id: getStringValue({ value: element.id, fallback: "" }),
 					name: getStringValue({ value: element.name, fallback: "" }),
 					type: "image",
@@ -369,7 +467,7 @@ async function transformMediaTrack({
 				return imageElement;
 			}

-			const videoElement: VideoElement = {
+			const videoElement: V2VideoElement = {
 				id: getStringValue({ value: element.id, fallback: "" }),
 				name: getStringValue({ value: element.name, fallback: "" }),
 				type: "video",
@@ -388,7 +486,7 @@ async function transformMediaTrack({
 	);

 	const validElements = transformedElements.filter(
-		(element): element is VideoElement | ImageElement => element !== null,
+		(element): element is V2VideoElement | V2ImageElement => element !== null,
 	);

 	return {
@@ -406,11 +504,11 @@ function transformTextTrack({
 	track,
 }: {
 	track: Record<string, unknown>;
-}): TimelineTrack {
+}): V2TextTrack {
 	const elements = Array.isArray(track.elements) ? track.elements : [];

 	const transformedElements = elements
-		.map((element): TextElement | null => {
+		.map((element): V2TextElement | null => {
 			if (!isRecord(element) || element.type !== "text") {
 				return null;
 			}
@@ -427,7 +525,7 @@ function transformTextTrack({
 				fallback: 1,
 			});

-			const transform: Transform = {
+			const transform: V2Transform = {
 				scale: 1,
 				position: { x, y },
 				rotate: rotation,
@@ -487,7 +585,7 @@ function transformTextTrack({
 				trimEnd: getNumberValue({ value: element.trimEnd, fallback: 0 }),
 			};
 		})
-		.filter((element): element is TextElement => element !== null);
+		.filter((element): element is V2TextElement => element !== null);

 	return {
 		id: getStringValue({ value: track.id, fallback: "" }),
@@ -502,11 +600,11 @@ function transformAudioTrack({
 	track,
 }: {
 	track: Record<string, unknown>;
-}): TimelineTrack {
+}): V2AudioTrack {
 	const elements = Array.isArray(track.elements) ? track.elements : [];

 	const transformedElements = elements
-		.map((element): AudioElement | null => {
+		.map((element): V2AudioElement | null => {
 			if (!isRecord(element) || element.type !== "audio") {
 				return null;
 			}
@@ -530,7 +628,7 @@ function transformAudioTrack({
 				trimEnd: getNumberValue({ value: element.trimEnd, fallback: 0 }),
 			};
 		})
-		.filter((element): element is AudioElement => element !== null);
+		.filter((element): element is V2AudioElement => element !== null);

 	return {
 		id: getStringValue({ value: track.id, fallback: "" }),
@@ -0,0 +1,113 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV10ToV11({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 11) {
+		return { project, skipped: true, reason: "already v11" };
+	}
+
+	const migratedProject = migrateProjectScale({ project });
+
+	return {
+		project: { ...migratedProject, version: 11 },
+		skipped: false,
+	};
+}
+
+function migrateProjectScale({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) return project;
+
+	const migratedScenes = scenesValue.map((scene) =>
+		migrateSceneScale({ scene }),
+	);
+
+	return { ...project, scenes: migratedScenes };
+}
+
+function migrateSceneScale({ scene }: { scene: unknown }): unknown {
+	if (!isRecord(scene)) return scene;
+
+	const tracksValue = scene.tracks;
+	if (!Array.isArray(tracksValue)) return scene;
+
+	const migratedTracks = tracksValue.map((track) =>
+		migrateTrackScale({ track }),
+	);
+
+	return { ...scene, tracks: migratedTracks };
+}
+
+function migrateTrackScale({ track }: { track: unknown }): unknown {
+	if (!isRecord(track)) return track;
+
+	const elementsValue = track.elements;
+	if (!Array.isArray(elementsValue)) return track;
+
+	const migratedElements = elementsValue.map((element) =>
+		migrateElementScale({ element }),
+	);
+
+	return { ...track, elements: migratedElements };
+}
+
+function migrateElementScale({ element }: { element: unknown }): unknown {
+	if (!isRecord(element)) return element;
+
+	const transform = element.transform;
+	if (!isRecord(transform)) return element;
+
+	const scale = transform.scale;
+	if (typeof scale !== "number") return element;
+
+	const migratedTransform = {
+		...transform,
+		scaleX: scale,
+		scaleY: scale,
+	};
+	delete (migratedTransform as Record<string, unknown>).scale;
+
+	let migratedElement: ProjectRecord = {
+		...element,
+		transform: migratedTransform,
+	};
+
+	const animations = element.animations;
+	if (isRecord(animations) && isRecord(animations.channels)) {
+		const channels = animations.channels as Record<string, unknown>;
+		const scaleChannel = channels["transform.scale"];
+		if (scaleChannel && isRecord(scaleChannel)) {
+			const keyframes = (scaleChannel as { keyframes?: unknown[] }).keyframes;
+			if (Array.isArray(keyframes)) {
+				const newChannels = { ...channels };
+				delete newChannels["transform.scale"];
+				newChannels["transform.scaleX"] = {
+					...scaleChannel,
+					keyframes: [...keyframes],
+				};
+				newChannels["transform.scaleY"] = {
+					...scaleChannel,
+					keyframes: keyframes.map((kf) => (isRecord(kf) ? { ...kf } : kf)),
+				};
+				migratedElement = {
+					...migratedElement,
+					animations: { ...animations, channels: newChannels },
+				};
+			}
+		}
+	}
+
+	return migratedElement;
+}
@@ -0,0 +1,196 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV11ToV12({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 12) {
+		return { project, skipped: true, reason: "already v12" };
+	}
+
+	const migratedProject = migrateProjectPosition({ project });
+
+	return {
+		project: { ...migratedProject, version: 12 },
+		skipped: false,
+	};
+}
+
+function migrateProjectPosition({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) return project;
+
+	const migratedScenes = scenesValue.map((scene) =>
+		migrateScenePosition({ scene }),
+	);
+
+	return { ...project, scenes: migratedScenes };
+}
+
+function migrateScenePosition({ scene }: { scene: unknown }): unknown {
+	if (!isRecord(scene)) return scene;
+
+	const tracksValue = scene.tracks;
+	if (!Array.isArray(tracksValue)) return scene;
+
+	const migratedTracks = tracksValue.map((track) =>
+		migrateTrackPosition({ track }),
+	);
+
+	return { ...scene, tracks: migratedTracks };
+}
+
+function migrateTrackPosition({ track }: { track: unknown }): unknown {
+	if (!isRecord(track)) return track;
+
+	const elementsValue = track.elements;
+	if (!Array.isArray(elementsValue)) return track;
+
+	const migratedElements = elementsValue.map((element) =>
+		migrateElementPosition({ element }),
+	);
+
+	return { ...track, elements: migratedElements };
+}
+
+function migrateElementPosition({ element }: { element: unknown }): unknown {
+	if (!isRecord(element)) return element;
+
+	const animations = element.animations;
+	if (!isRecord(animations) || !isRecord(animations.channels)) return element;
+
+	const channels = animations.channels as Record<string, unknown>;
+	const xChannel = channels["transform.position.x"];
+	const yChannel = channels["transform.position.y"];
+
+	if (!xChannel && !yChannel) return element;
+
+	const baseTransform = isRecord(element.transform) ? element.transform : {};
+	const basePosition = isRecord(baseTransform.position)
+		? baseTransform.position
+		: {};
+	const baseX = typeof basePosition.x === "number" ? basePosition.x : 0;
+	const baseY = typeof basePosition.y === "number" ? basePosition.y : 0;
+
+	const xKeyframes = getKeyframes({ channel: xChannel });
+	const yKeyframes = getKeyframes({ channel: yChannel });
+
+	const allTimes = Array.from(
+		new Set([
+			...xKeyframes.map((kf) => kf.time),
+			...yKeyframes.map((kf) => kf.time),
+		]),
+	).sort((a, b) => a - b);
+
+	const vectorKeyframes = allTimes.map((time) => {
+		const xKf = xKeyframes.find((kf) => Math.abs(kf.time - time) < 0.001);
+		const yKf = yKeyframes.find((kf) => Math.abs(kf.time - time) < 0.001);
+		const x =
+			typeof xKf?.value === "number"
+				? xKf.value
+				: interpolateScalarAtTime({
+						keyframes: xKeyframes,
+						time,
+						fallback: baseX,
+					});
+		const y =
+			typeof yKf?.value === "number"
+				? yKf.value
+				: interpolateScalarAtTime({
+						keyframes: yKeyframes,
+						time,
+						fallback: baseY,
+					});
+		const interpolation = xKf?.interpolation ?? yKf?.interpolation ?? "linear";
+		return {
+			id: xKf?.id ?? yKf?.id ?? crypto.randomUUID(),
+			time,
+			value: { x, y },
+			interpolation,
+		};
+	});
+
+	const newChannels = { ...channels };
+	delete newChannels["transform.position.x"];
+	delete newChannels["transform.position.y"];
+	newChannels["transform.position"] = {
+		valueKind: "vector",
+		keyframes: vectorKeyframes,
+	};
+
+	return {
+		...element,
+		animations: { ...animations, channels: newChannels },
+	};
+}
+
+interface ScalarKeyframe {
+	id: string;
+	time: number;
+	value: number;
+	interpolation: string;
+}
+
+function getKeyframes({ channel }: { channel: unknown }): ScalarKeyframe[] {
+	if (!isRecord(channel)) return [];
+	if (!Array.isArray(channel.keyframes)) return [];
+	return channel.keyframes.flatMap((kf) => {
+		if (!isRecord(kf)) return [];
+		if (
+			typeof kf.id !== "string" ||
+			typeof kf.time !== "number" ||
+			typeof kf.value !== "number"
+		)
+			return [];
+		return [
+			{
+				id: kf.id,
+				time: kf.time,
+				value: kf.value,
+				interpolation:
+					typeof kf.interpolation === "string" ? kf.interpolation : "linear",
+			},
+		];
+	});
+}
+
+function interpolateScalarAtTime({
+	keyframes,
+	time,
+	fallback,
+}: {
+	keyframes: ScalarKeyframe[];
+	time: number;
+	fallback: number;
+}): number {
+	if (keyframes.length === 0) return fallback;
+
+	const sorted = [...keyframes].sort((a, b) => a.time - b.time);
+	const first = sorted[0];
+	const last = sorted[sorted.length - 1];
+
+	if (!first || !last) return fallback;
+	if (time <= first.time) return first.value;
+	if (time >= last.time) return last.value;
+
+	for (let i = 0; i < sorted.length - 1; i++) {
+		const left = sorted[i];
+		const right = sorted[i + 1];
+		if (time < left.time || time > right.time) continue;
+		if (left.interpolation === "hold") return left.value;
+		const t = (time - left.time) / (right.time - left.time);
+		return left.value + (right.value - left.value) * t;
+	}
+
+	return last.value;
+}
@@ -0,0 +1,102 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV12ToV13({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 13) {
+		return { project, skipped: true, reason: "already v13" };
+	}
+
+	const migratedProject = migrateProjectMasks({ project });
+
+	return {
+		project: { ...migratedProject, version: 13 },
+		skipped: false,
+	};
+}
+
+function migrateProjectMasks({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) return project;
+
+	const migratedScenes = scenesValue.map((scene) =>
+		migrateSceneMasks({ scene }),
+	);
+
+	return { ...project, scenes: migratedScenes };
+}
+
+function migrateSceneMasks({ scene }: { scene: unknown }): unknown {
+	if (!isRecord(scene)) return scene;
+
+	const tracksValue = scene.tracks;
+	if (!Array.isArray(tracksValue)) return scene;
+
+	const migratedTracks = tracksValue.map((track) =>
+		migrateTrackMasks({ track }),
+	);
+
+	return { ...scene, tracks: migratedTracks };
+}
+
+function migrateTrackMasks({ track }: { track: unknown }): unknown {
+	if (!isRecord(track)) return track;
+
+	const elementsValue = track.elements;
+	if (!Array.isArray(elementsValue)) return track;
+
+	const migratedElements = elementsValue.map((element) =>
+		migrateElementMasks({ element }),
+	);
+
+	return { ...track, elements: migratedElements };
+}
+
+function migrateElementMasks({ element }: { element: unknown }): unknown {
+	if (!isRecord(element)) return element;
+
+	const masksValue = element.masks;
+	if (!Array.isArray(masksValue)) return element;
+
+	const migratedMasks = masksValue.map((mask) => migrateMask({ mask }));
+
+	return { ...element, masks: migratedMasks };
+}
+
+function migrateMask({ mask }: { mask: unknown }): unknown {
+	if (!isRecord(mask)) return mask;
+
+	const params = isRecord(mask.params) ? { ...mask.params } : {};
+	const result = { ...mask };
+
+	result.params = {
+		...params,
+		feather: typeof mask.feather === "number" ? mask.feather : 0,
+		inverted: typeof mask.inverted === "boolean" ? mask.inverted : false,
+		strokeColor:
+			isRecord(mask.stroke) && typeof mask.stroke.color === "string"
+				? mask.stroke.color
+				: "#ffffff",
+		strokeWidth:
+			isRecord(mask.stroke) && typeof mask.stroke.width === "number"
+				? mask.stroke.width
+				: 0,
+	};
+
+	delete (result as Record<string, unknown>).feather;
+	delete (result as Record<string, unknown>).inverted;
+	delete (result as Record<string, unknown>).stroke;
+
+	return result;
+}
@@ -0,0 +1,106 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV13ToV14({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 14) {
+		return { project, skipped: true, reason: "already v14" };
+	}
+
+	const migratedProject = migrateProjectSplitMasks({ project });
+
+	return {
+		project: { ...migratedProject, version: 14 },
+		skipped: false,
+	};
+}
+
+function migrateProjectSplitMasks({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) return project;
+
+	const migratedScenes = scenesValue.map((scene) =>
+		migrateSceneSplitMasks({ scene }),
+	);
+
+	return { ...project, scenes: migratedScenes };
+}
+
+function migrateSceneSplitMasks({ scene }: { scene: unknown }): unknown {
+	if (!isRecord(scene)) return scene;
+
+	const tracksValue = scene.tracks;
+	if (!Array.isArray(tracksValue)) return scene;
+
+	const migratedTracks = tracksValue.map((track) =>
+		migrateTrackSplitMasks({ track }),
+	);
+
+	return { ...scene, tracks: migratedTracks };
+}
+
+function migrateTrackSplitMasks({ track }: { track: unknown }): unknown {
+	if (!isRecord(track)) return track;
+
+	const elementsValue = track.elements;
+	if (!Array.isArray(elementsValue)) return track;
+
+	const migratedElements = elementsValue.map((element) =>
+		migrateElementSplitMasks({ element }),
+	);
+
+	return { ...track, elements: migratedElements };
+}
+
+function migrateElementSplitMasks({ element }: { element: unknown }): unknown {
+	if (!isRecord(element)) return element;
+
+	const masksValue = element.masks;
+	if (!Array.isArray(masksValue)) return element;
+
+	const migratedMasks = masksValue.map((mask) => migrateSplitMask({ mask }));
+
+	return { ...element, masks: migratedMasks };
+}
+
+/**
+ * Converts split mask params from position-along-normal to explicit (x, y) anchor.
+ *
+ * Old: center = (cx + (position-0.5)*W*cos(rot), cy + (position-0.5)*W*sin(rot))
+ * New: center = (cx + x*W, cy + y*W)
+ *
+ * Conversion: x = (position-0.5)*cos(rot), y = (position-0.5)*sin(rot)
+ */
+function migrateSplitMask({ mask }: { mask: unknown }): unknown {
+	if (!isRecord(mask)) return mask;
+	if (mask.type !== "split") return mask;
+
+	const params = isRecord(mask.params) ? mask.params : {};
+	const position = typeof params.position === "number" ? params.position : 0.5;
+	const rotation = typeof params.rotation === "number" ? params.rotation : 0;
+
+	const angleRad = (rotation * Math.PI) / 180;
+	const x = (position - 0.5) * Math.cos(angleRad);
+	const y = (position - 0.5) * Math.sin(angleRad);
+
+	const { position: _removed, ...restParams } = params as Record<
+		string,
+		unknown
+	> & { position: unknown };
+
+	return {
+		...mask,
+		params: { ...restParams, x, y },
+	};
+}
@@ -0,0 +1,67 @@
+import { STICKER_INTRINSIC_SIZE_FALLBACK } from "@/constants/sticker-constants";
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV14ToV15({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 15) {
+		return { project, skipped: true, reason: "already v15" };
+	}
+
+	const migratedProject = backfillStickerIntrinsicDimensions({ project });
+
+	return {
+		project: { ...migratedProject, version: 15 },
+		skipped: false,
+	};
+}
+
+function backfillStickerIntrinsicDimensions({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) return project;
+
+	const migratedScenes = scenesValue.map((scene) => {
+		if (!isRecord(scene)) return scene;
+		const tracksValue = scene.tracks;
+		if (!Array.isArray(tracksValue)) return scene;
+
+		const migratedTracks = tracksValue.map((track) => {
+			if (!isRecord(track)) return track;
+			const elementsValue = track.elements;
+			if (!Array.isArray(elementsValue)) return track;
+
+			const migratedElements = elementsValue.map((element) => {
+				if (!isRecord(element)) return element;
+				if (element.type !== "sticker") return element;
+				if (
+					typeof element.intrinsicWidth === "number" &&
+					typeof element.intrinsicHeight === "number"
+				) {
+					return element;
+				}
+				return {
+					...element,
+					intrinsicWidth: STICKER_INTRINSIC_SIZE_FALLBACK,
+					intrinsicHeight: STICKER_INTRINSIC_SIZE_FALLBACK,
+				};
+			});
+
+			return { ...track, elements: migratedElements };
+		});
+
+		return { ...scene, tracks: migratedTracks };
+	});
+
+	return { ...project, scenes: migratedScenes };
+}
@@ -0,0 +1,60 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV15ToV16({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 16) {
+		return { project, skipped: true, reason: "already v16" };
+	}
+
+	return {
+		project: {
+			...renameStickerTracksToGraphic({ project }),
+			version: 16,
+		},
+		skipped: false,
+	};
+}
+
+function renameStickerTracksToGraphic({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) {
+		return project;
+	}
+
+	const migratedScenes = scenesValue.map((scene) => {
+		if (!isRecord(scene) || !Array.isArray(scene.tracks)) {
+			return scene;
+		}
+
+		return {
+			...scene,
+			tracks: scene.tracks.map((track) => {
+				if (!isRecord(track) || track.type !== "sticker") {
+					return track;
+				}
+
+				return {
+					...track,
+					type: "graphic",
+				};
+			}),
+		};
+	});
+
+	return {
+		...project,
+		scenes: migratedScenes,
+	};
+}
@@ -0,0 +1,107 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV16ToV17({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 17) {
+		return { project, skipped: true, reason: "already v17" };
+	}
+
+	return {
+		project: {
+			...backfillMaskStrokeAlign({ project }),
+			version: 17,
+		},
+		skipped: false,
+	};
+}
+
+function backfillMaskStrokeAlign({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) {
+		return project;
+	}
+
+	const migratedScenes = scenesValue.map((scene) => {
+		if (!isRecord(scene)) {
+			return scene;
+		}
+
+		const tracksValue = scene.tracks;
+		if (!Array.isArray(tracksValue)) {
+			return scene;
+		}
+
+		const migratedTracks = tracksValue.map((track) => {
+			if (!isRecord(track)) {
+				return track;
+			}
+
+			const elementsValue = track.elements;
+			if (!Array.isArray(elementsValue)) {
+				return track;
+			}
+
+			const migratedElements = elementsValue.map((element) => {
+				if (!isRecord(element)) {
+					return element;
+				}
+
+				const masksValue = element.masks;
+				if (!Array.isArray(masksValue)) {
+					return element;
+				}
+
+				const migratedMasks = masksValue.map((mask) => {
+					if (!isRecord(mask)) {
+						return mask;
+					}
+
+					const paramsValue = mask.params;
+					if (!isRecord(paramsValue) || typeof paramsValue.strokeAlign === "string") {
+						return mask;
+					}
+
+					return {
+						...mask,
+						params: {
+							...paramsValue,
+							strokeAlign: "center",
+						},
+					};
+				});
+
+				return {
+					...element,
+					masks: migratedMasks,
+				};
+			});
+
+			return {
+				...track,
+				elements: migratedElements,
+			};
+		});
+
+		return {
+			...scene,
+			tracks: migratedTracks,
+		};
+	});
+
+	return {
+		...project,
+		scenes: migratedScenes,
+	};
+}
@@ -0,0 +1,105 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { VOLUME_DB_MIN } from "@/lib/timeline/audio-constants";
+import { clampDb } from "@/lib/timeline/audio-state";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV17ToV18({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 18) {
+		return { project, skipped: true, reason: "already v18" };
+	}
+
+	return {
+		project: {
+			...migrateElementVolumes({ project }),
+			version: 18,
+		},
+		skipped: false,
+	};
+}
+
+function migrateElementVolumes({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const scenesValue = project.scenes;
+	if (!Array.isArray(scenesValue)) {
+		return project;
+	}
+
+	const migratedScenes = scenesValue.map((scene) => {
+		if (!isRecord(scene)) {
+			return scene;
+		}
+
+		const tracksValue = scene.tracks;
+		if (!Array.isArray(tracksValue)) {
+			return scene;
+		}
+
+		const migratedTracks = tracksValue.map((track) => {
+			if (!isRecord(track)) {
+				return track;
+			}
+
+			const elementsValue = track.elements;
+			if (!Array.isArray(elementsValue)) {
+				return track;
+			}
+
+			const migratedElements = elementsValue.map((element) => {
+				if (!isRecord(element)) {
+					return element;
+				}
+
+				if (element.type !== "audio" && element.type !== "video") {
+					return element;
+				}
+
+				const legacyVolume = element.volume;
+				return {
+					...element,
+					volume:
+						typeof legacyVolume === "number"
+							? linearGainToDb(legacyVolume)
+							: 0,
+				};
+			});
+
+			return {
+				...track,
+				elements: migratedElements,
+			};
+		});
+
+		return {
+			...scene,
+			tracks: migratedTracks,
+		};
+	});
+
+	return {
+		...project,
+		scenes: migratedScenes,
+	};
+}
+
+function linearGainToDb(gain: number): number {
+	if (!Number.isFinite(gain)) {
+		return 0;
+	}
+
+	if (gain <= 0) {
+		return VOLUME_DB_MIN;
+	}
+
+	return clampDb(20 * Math.log10(gain));
+}
@@ -0,0 +1,46 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId, isRecord } from "./utils";
+
+export function transformProjectV18ToV19({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 19) {
+		return { project, skipped: true, reason: "already v19" };
+	}
+
+	return {
+		project: {
+			...migrateCanvasSizeSettings({ project }),
+			version: 19,
+		},
+		skipped: false,
+	};
+}
+
+function migrateCanvasSizeSettings({
+	project,
+}: {
+	project: ProjectRecord;
+}): ProjectRecord {
+	const settingsValue = project.settings;
+	if (!isRecord(settingsValue)) {
+		return project;
+	}
+
+	const migratedSettings: Record<string, unknown> = {
+		...settingsValue,
+		canvasSizeMode: "preset",
+		lastCustomCanvasSize: null,
+	};
+
+	return {
+		...project,
+		settings: migratedSettings,
+	};
+}
@@ -1,5 +1,3 @@
-import { getProjectDurationFromScenes } from "@/lib/scenes";
-import type { TScene } from "@/types/timeline";
 import type { MigrationResult, ProjectRecord } from "./types";
 import { getProjectId, isRecord } from "./utils";

@@ -18,7 +16,7 @@ export function transformProjectV2ToV3({
 	}

 	const scenes = getScenes({ project });
-	const duration = getProjectDurationFromScenes({ scenes });
+	const duration = getDurationFromScenes({ scenes });

 	const metadataValue = project.metadata;
 	const metadata = isRecord(metadataValue)
@@ -36,13 +34,42 @@ export function transformProjectV2ToV3({

 export { getProjectId } from "./utils";

-function getScenes({ project }: { project: ProjectRecord }): TScene[] {
+function getScenes({ project }: { project: ProjectRecord }): unknown[] {
 	const scenesValue = project.scenes;
 	if (!Array.isArray(scenesValue)) {
 		return [];
 	}

-	return scenesValue.filter(isRecord) as unknown as TScene[];
+	return scenesValue.filter(isRecord);
+}
+
+function getDurationFromScenes({ scenes }: { scenes: unknown[] }): number {
+	const mainScene =
+		scenes.find(
+			(s): s is Record<string, unknown> =>
+				isRecord(s) && s.isMain === true,
+		) ??
+		scenes.find(isRecord) ??
+		null;
+
+	if (!mainScene || !Array.isArray(mainScene.tracks)) {
+		return 0;
+	}
+
+	let maxEnd = 0;
+	for (const track of mainScene.tracks) {
+		if (!isRecord(track) || !Array.isArray(track.elements)) continue;
+		for (const element of track.elements) {
+			if (!isRecord(element)) continue;
+			const startTime =
+				typeof element.startTime === "number" ? element.startTime : 0;
+			const duration =
+				typeof element.duration === "number" ? element.duration : 0;
+			maxEnd = Math.max(maxEnd, startTime + duration);
+		}
+	}
+
+	return maxEnd;
 }

 function isV3Project({ project }: { project: ProjectRecord }): boolean {
@@ -0,0 +1,21 @@
+import type { MigrationResult, ProjectRecord } from "./types";
+import { getProjectId } from "./utils";
+
+export function transformProjectV9ToV10({
+	project,
+}: {
+	project: ProjectRecord;
+}): MigrationResult<ProjectRecord> {
+	if (!getProjectId({ project })) {
+		return { project, skipped: true, reason: "no project id" };
+	}
+
+	if (typeof project.version === "number" && project.version >= 10) {
+		return { project, skipped: true, reason: "already v10" };
+	}
+
+	return {
+		project: { ...project, version: 10 },
+		skipped: false,
+	};
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV10ToV11 } from "./transformers/v10-to-v11";
+
+export class V10toV11Migration extends StorageMigration {
+	from = 10;
+	to = 11;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV10ToV11({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV11ToV12 } from "./transformers/v11-to-v12";
+
+export class V11toV12Migration extends StorageMigration {
+	from = 11;
+	to = 12;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV11ToV12({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV12ToV13 } from "./transformers/v12-to-v13";
+
+export class V12toV13Migration extends StorageMigration {
+	from = 12;
+	to = 13;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV12ToV13({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV13ToV14 } from "./transformers/v13-to-v14";
+
+export class V13toV14Migration extends StorageMigration {
+	from = 13;
+	to = 14;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV13ToV14({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV14ToV15 } from "./transformers/v14-to-v15";
+
+export class V14toV15Migration extends StorageMigration {
+	from = 14;
+	to = 15;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV14ToV15({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV15ToV16 } from "./transformers/v15-to-v16";
+
+export class V15toV16Migration extends StorageMigration {
+	from = 15;
+	to = 16;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV15ToV16({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV16ToV17 } from "./transformers/v16-to-v17";
+
+export class V16toV17Migration extends StorageMigration {
+	from = 16;
+	to = 17;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV16ToV17({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV17ToV18 } from "./transformers/v17-to-v18";
+
+export class V17toV18Migration extends StorageMigration {
+	from = 17;
+	to = 18;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV17ToV18({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV18ToV19 } from "./transformers/v18-to-v19";
+
+export class V18toV19Migration extends StorageMigration {
+	from = 18;
+	to = 19;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV18ToV19({ project });
+	}
+}
@@ -0,0 +1,16 @@
+import { StorageMigration } from "./base";
+import type { ProjectRecord } from "./transformers/types";
+import { transformProjectV9ToV10 } from "./transformers/v9-to-v10";
+
+export class V9toV10Migration extends StorageMigration {
+	from = 9;
+	to = 10;
+
+	async transform(project: ProjectRecord): Promise<{
+		project: ProjectRecord;
+		skipped: boolean;
+		reason?: string;
+	}> {
+		return transformProjectV9ToV10({ project });
+	}
+}
@@ -0,0 +1,145 @@
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB"] as const;
+
+export const STORAGE_HEADROOM_RESERVE_BYTES = 50 * 1024 * 1024;
+
+export interface StorageQuotaStatus {
+	quotaBytes: number | null;
+	usageBytes: number | null;
+	headroomBytes: number | null;
+	availableBytes: number | null;
+}
+
+export interface StorageCapacityCheckResult {
+	canStore: boolean;
+	reason: "enough-space" | "insufficient-space" | "estimate-unavailable";
+	availableBytes: number | null;
+}
+
+function normalizeByteValue({ value }: { value: unknown }): number | null {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		return null;
+	}
+
+	return value;
+}
+
+export function formatStorageBytes({ bytes }: { bytes: number }): string {
+	if (!Number.isFinite(bytes) || bytes <= 0) {
+		return "0 B";
+	}
+
+	let value = bytes;
+	let unitIndex = 0;
+
+	while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+		value /= 1024;
+		unitIndex += 1;
+	}
+
+	const precision = value >= 10 || unitIndex === 0 ? 0 : 1;
+	return `${value.toFixed(precision)} ${BYTE_UNITS[unitIndex]}`;
+}
+
+export async function readStorageQuotaStatus(): Promise<StorageQuotaStatus> {
+	if (
+		typeof navigator === "undefined" ||
+		!navigator.storage ||
+		typeof navigator.storage.estimate !== "function"
+	) {
+		return {
+			quotaBytes: null,
+			usageBytes: null,
+			headroomBytes: null,
+			availableBytes: null,
+		};
+	}
+
+	const estimate = await navigator.storage.estimate();
+	const quotaBytes = normalizeByteValue({ value: estimate.quota });
+	const usageBytes = normalizeByteValue({ value: estimate.usage });
+
+	if (quotaBytes === null || usageBytes === null) {
+		return {
+			quotaBytes,
+			usageBytes,
+			headroomBytes: null,
+			availableBytes: null,
+		};
+	}
+
+	const headroomBytes = Math.max(quotaBytes - usageBytes, 0);
+	const availableBytes = Math.max(
+		headroomBytes - STORAGE_HEADROOM_RESERVE_BYTES,
+		0,
+	);
+
+	return {
+		quotaBytes,
+		usageBytes,
+		headroomBytes,
+		availableBytes,
+	};
+}
+
+export function evaluateStorageCapacity({
+	requiredBytes,
+	quotaStatus,
+}: {
+	requiredBytes: number;
+	quotaStatus: StorageQuotaStatus;
+}): StorageCapacityCheckResult {
+	if (quotaStatus.availableBytes === null) {
+		return {
+			canStore: true,
+			reason: "estimate-unavailable",
+			availableBytes: null,
+		};
+	}
+
+	if (requiredBytes > quotaStatus.availableBytes) {
+		return {
+			canStore: false,
+			reason: "insufficient-space",
+			availableBytes: quotaStatus.availableBytes,
+		};
+	}
+
+	return {
+		canStore: true,
+		reason: "enough-space",
+		availableBytes: quotaStatus.availableBytes,
+	};
+}
+
+export class StorageQuotaExceededError extends Error {
+	requiredBytes: number;
+
+	constructor({ requiredBytes }: { requiredBytes: number }) {
+		super(
+			`Not enough browser storage to save a ${formatStorageBytes({ bytes: requiredBytes })} file.`,
+		);
+
+		this.name = "StorageQuotaExceededError";
+		this.requiredBytes = requiredBytes;
+	}
+}
+
+export function isStorageQuotaExceededError({
+	error,
+}: {
+	error: unknown;
+}): boolean {
+	if (error instanceof StorageQuotaExceededError) {
+		return true;
+	}
+
+	if (!(error instanceof Error)) {
+		return false;
+	}
+
+	return (
+		error.name === "QuotaExceededError" ||
+		error.name === "NS_ERROR_DOM_QUOTA_REACHED" ||
+		error.message.toLowerCase().includes("quota")
+	);
+}
@@ -1,20 +1,27 @@
-import type { TProject, TProjectMetadata } from "@/types/project";
+import type { TProject, TProjectMetadata } from "@/lib/project/types";
 import { getProjectDurationFromScenes } from "@/lib/scenes";
-import type { MediaAsset } from "@/types/assets";
+import type { MediaAsset } from "@/lib/media/types";
 import { IndexedDBAdapter } from "./indexeddb-adapter";
 import { OPFSAdapter } from "./opfs-adapter";
+import {
+	type StorageCapacityCheckResult,
+	StorageQuotaExceededError,
+	evaluateStorageCapacity,
+	isStorageQuotaExceededError,
+	readStorageQuotaStatus,
+} from "./quota";
 import type {
 	MediaAssetData,
 	StorageConfig,
 	SerializedProject,
 	SerializedScene,
 } from "./types";
-import type { SavedSoundsData, SavedSound, SoundEffect } from "@/types/sounds";
+import type { SavedSoundsData, SavedSound, SoundEffect } from "@/lib/sounds/types";
 import {
 	migrations,
 	runStorageMigrations,
 } from "@/services/storage/migrations";
-import type { Bookmark, TimelineTrack, TScene } from "@/types/timeline";
+import type { Bookmark, TimelineTrack, TScene } from "@/lib/timeline";

 function normalizeBookmarks({ raw }: { raw: unknown }): Bookmark[] {
 	if (!Array.isArray(raw)) return [];
@@ -90,6 +97,22 @@ class StorageService {
 		return { mediaMetadataAdapter, mediaAssetsAdapter };
 	}

+	async canStoreFile({
+		size,
+	}: {
+		size: number;
+	}): Promise<StorageCapacityCheckResult> {
+		const quotaStatus = await readStorageQuotaStatus();
+		return evaluateStorageCapacity({
+			requiredBytes: size,
+			quotaStatus,
+		});
+	}
+
+	isQuotaExceededError({ error }: { error: unknown }): boolean {
+		return isStorageQuotaExceededError({ error });
+	}
+
 	private stripAudioBuffers({
 		tracks,
 	}: {
@@ -238,8 +261,6 @@ class StorageService {
 		const { mediaMetadataAdapter, mediaAssetsAdapter } =
 			this.getProjectMediaAdapters({ projectId });

-		await mediaAssetsAdapter.set(mediaAsset.id, mediaAsset.file);
-
 		const metadata: MediaAssetData = {
 			id: mediaAsset.id,
 			name: mediaAsset.name,
@@ -253,7 +274,24 @@ class StorageService {
 			ephemeral: mediaAsset.ephemeral,
 		};

-		await mediaMetadataAdapter.set(mediaAsset.id, metadata);
+		try {
+			await mediaAssetsAdapter.set(mediaAsset.id, mediaAsset.file);
+			await mediaMetadataAdapter.set(mediaAsset.id, metadata);
+		} catch (error) {
+			try {
+				await mediaAssetsAdapter.remove(mediaAsset.id);
+			} catch {
+				// Ignore cleanup failures so the original storage error is preserved.
+			}
+
+			if (this.isQuotaExceededError({ error })) {
+				throw new StorageQuotaExceededError({
+					requiredBytes: mediaAsset.file.size,
+				});
+			}
+
+			throw error;
+		}
 	}

 	async loadMediaAsset({
@@ -1,10 +1,10 @@
-import type { MediaType } from "@/types/assets";
+import type { MediaType } from "@/lib/media/types";
 import type {
 	TProject,
 	TProjectMetadata,
 	TTimelineViewState,
-} from "@/types/project";
-import type { TScene } from "@/types/timeline";
+} from "@/lib/project/types";
+import type { TScene } from "@/lib/timeline";

 export interface StorageAdapter<T> {
 	get(key: string): Promise<T | null>;
@@ -24,6 +24,7 @@ export interface MediaAssetData {
 	height?: number;
 	duration?: number;
 	fps?: number;
+	hasAudio?: boolean;
 	ephemeral?: boolean;
 	thumbnailUrl?: string;
 }
@@ -3,7 +3,7 @@ import type {
 	TranscriptionResult,
 	TranscriptionProgress,
 	TranscriptionModelId,
-} from "@/types/transcription";
+} from "@/lib/transcription/types";
 import {
 	DEFAULT_TRANSCRIPTION_MODEL,
 	TRANSCRIPTION_MODELS,
@@ -3,7 +3,7 @@ import {
 	type AutomaticSpeechRecognitionPipeline,
 	type AutomaticSpeechRecognitionOutput,
 } from "@huggingface/transformers";
-import type { TranscriptionSegment } from "@/types/transcription";
+import type { TranscriptionSegment } from "@/lib/transcription/types";
 import {
 	DEFAULT_CHUNK_LENGTH_SECONDS,
 	DEFAULT_STRIDE_SECONDS,