refactor: drop legacy 'native' AspectRatio via v6 schema migration

(1) Bumped axcutSchemaVersion 5 -> 6 and added upgradeV5DocumentToV6,
    which rewrites every stored legacyEditor.aspectRatio === "native"
    to a concrete "W:H" token (the timeline's largest clip dims,
    falling back to "16:9"). The upgrader is wired into the existing
    z.preprocess chain alongside v3->v4 and v4->v5.

(2) Dropped the "native" union arm from AspectRatio and the
    per-helper branches in getAspectRatioValue / getAspectRatioLabel /
    isAspectRatio / formatAspectRatioForCSS. Renamed
    NATIVE_ASPECT_RATIO_FALLBACK -> ASPECT_RATIO_FALLBACK (the
    file-private fallback). getNativeAspectRatioValue is kept.

(3) Removed the runtime bridge in outputFormat.resolveAspectRatioValue
    (it was document-aware to resolve "native") and the self-migration
    useMemo in V4Timeline (the activeToken that re-mapped
    settings.aspectRatio to the largest clip's token). Both are dead
    now that v6 documents cannot contain "native". Updated the three
    preview/export call sites to the new one-arg signature.

(4) Tests: bumped every existing schemaVersion === 5 assertion to 6
    (schema, migrate, document-service), added a 7-test v5->v6
    migration block in schema/index.test.ts, and stripped the "native"
    assertions from aspectRatioUtils and outputFormat tests (pointing
    at the v5->v6 upgrader tests as the new home).

Intentionally untouched: lastBackgroundColor. The original audit
recommended dropping it as dead code, but the picker swatch in
src/lib/ai-edition/annotations/background.ts:25-29 reads it for the
swatch when bg is off, and toggleTextBackground writes it on every
toggle — it's the fix for the "background toggle always reverts to
black" regression.

Author: EtienneLescot

electron/ai-edition/document-service.test.ts

@@ -24,17 +24,17 @@ describe("DocumentService", () => {
 	});
 
 	describe("createProject", () => {
-		it("creates a v5 doc with the given title and writes it to disk", async () => {
+		it("creates a v6 doc with the given title and writes it to disk", async () => {
 			const doc = await service.createProject("Demo Project");
-			expect(doc.schemaVersion).toBe(5);
+			expect(doc.schemaVersion).toBe(6);
 			expect(doc.project.title).toBe("Demo Project");
 			expect(doc.project.id).toMatch(/^proj_/);
 			expect(doc.assets).toEqual([]);
 
 			const filePath = path.join(tempDir, `${doc.project.id}.openscreen`);
 			const raw = await fs.readFile(filePath, "utf8");
 			expect(JSON.parse(raw)).toMatchObject({
-				schemaVersion: 5,
+				schemaVersion: 6,
 				project: { title: "Demo Project" },
 			});
 		});

src/components/ai-edition/ExportDialog.tsx

@@ -183,9 +183,10 @@ export function ExportDialog({ open, onClose, document }: ExportDialogProps) {
 	// so the sizes shown match what the export produces. Read through `getEditorSettings` — the
 	// same typed façade the ratio dropdown writes through and `buildSceneDescription` reads — so
 	// this dialog can't drift from the compositor if the storage ever moves. `resolveAspectRatioValue`
-	// owns the legacy "native" case (uncropped reference asset), previously hand-rolled here.
+	// is the single funnel preview and export agree on; the v5→v6 upgrader retires the legacy
+	// "native" AspectRatio so no document-context argument is needed here.
 	const EXPORT_ASPECT = useMemo(
-		() => resolveAspectRatioValue(document, getEditorSettings(document).aspectRatio),
+		() => resolveAspectRatioValue(getEditorSettings(document).aspectRatio),
 		[document],
 	);
 	// Output dimensions the export will produce for a given tier, from the (crop-aware)

src/components/ai-edition/PreviewCanvas.tsx

@@ -188,12 +188,12 @@ export function PreviewCanvas(props: PreviewCanvasProps) {
 	// exactly what the frame is styled to (`width: frameSize.width` a few lines below), so it's
 	// used directly everywhere `canvasSize` used to be — one source of truth, no separate
 	// observer that can desync from it.
-	// `resolveAspectRatioValue`, not bare `getAspectRatioValue`: the latter has no document to
-	// resolve the legacy "native" selection against and answers 16/9 for it, so a project saved
-	// with "native" over portrait footage framed the preview 16:9 while `pickOutputDims` handed
-	// the compositor a portrait `output` — preview and export disagreed on the frame's shape.
+	// `resolveAspectRatioValue`, not bare `getAspectRatioValue`: keeps preview and export
+	// routing through the same funnel — the v5→v6 upgrader rewrites the legacy "native"
+	// selection to a concrete `"W:H"` token, so both paths agree on the resolved shape
+	// without an extra document argument.
 	const frameSize = useMemo(() => {
-		const ratio = resolveAspectRatioValue(document, settings.aspectRatio);
+		const ratio = resolveAspectRatioValue(settings.aspectRatio);
 		const { width: containerWidth, height: containerHeight } = containerSize;
 		if (containerWidth <= 0 || containerHeight <= 0)
 			return { width: containerWidth, height: containerHeight };
@@ -203,7 +203,7 @@ export function PreviewCanvas(props: PreviewCanvasProps) {
 		}
 		const width = containerWidth;
 		return { width: Math.round(width), height: Math.round(width / ratio) };
-	}, [containerSize, settings.aspectRatio, document]);
+	}, [containerSize, settings.aspectRatio]);
 
 	// Crop is per-clip (see clipSchema.cropRegion) — resolve it from whichever
 	// clip the playhead is currently inside, the same lookup VirtualPreview

src/components/ai-edition/v4/V4Timeline.tsx

@@ -30,7 +30,7 @@ import { ZOOM_DEPTH_SCALES } from "@/components/video-editor/types";
 import { useScopedT } from "@/contexts/I18nContext";
 import { useAudioPeaks } from "@/hooks/useAudioPeaks";
 import { createId } from "@/lib/ai-edition/document/ids";
-import { collectNativeFormats, referenceClipDims } from "@/lib/ai-edition/document/outputFormat";
+import { collectNativeFormats } from "@/lib/ai-edition/document/outputFormat";
 import type { AxcutClip } from "@/lib/ai-edition/schema";
 import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
 import { useChatPromptBus } from "@/lib/ai-edition/store/useChatPromptBus";
@@ -46,11 +46,7 @@ import {
 } from "@/lib/ai-edition/timeline/trim-mapping";
 import { buildAutoZoomSuggestions } from "@/lib/ai-edition/timeline/zoom-suggestions";
 import { nativeBridgeClient } from "@/native/client";
-import {
-	ASPECT_RATIO_PRESETS,
-	getAspectRatioLabel,
-	toAspectRatioToken,
-} from "@/utils/aspectRatioUtils";
+import { ASPECT_RATIO_PRESETS, getAspectRatioLabel } from "@/utils/aspectRatioUtils";
 import { TransportBar } from "../TransportBar";
 import type { VideoSource } from "../VirtualPreview";
 import styles from "./EditorShellV4.module.css";
@@ -271,16 +267,6 @@ export function V4Timeline({
 	// stays a pure list of fixed choices, and "which shapes are my clips" lives solely in ORIGINAL
 	// (no more per-preset badge, which split that one answer across two places).
 	const timelineIsMixed = nativeFormats.length > 1;
-	// A project saved before the shapes were enumerated still stores "native". Resolve it to the
-	// shape it currently means so the menu highlights a real row (and the button names a real
-	// ratio) instead of showing a selection that matches nothing. Picking that row rewrites the
-	// document to the concrete token — which is how those projects self-migrate off the value
-	// that silently moved with the clip list.
-	const activeToken = useMemo(() => {
-		if (settings.aspectRatio !== "native" || !document) return settings.aspectRatio;
-		const reference = referenceClipDims(document);
-		return toAspectRatioToken(reference.width, reference.height) ?? settings.aspectRatio;
-	}, [settings.aspectRatio, document]);
 
 	const [aspectMenuOpen, setAspectMenuOpen] = useState(false);
 	const [autoEnhanceOpen, setAutoEnhanceOpen] = useState(false);
@@ -1115,7 +1101,7 @@ export function V4Timeline({
 									title={t("toolbar.aspectRatio")}
 									aria-label={t("toolbar.aspectRatio")}
 								>
-									{getAspectRatioLabel(activeToken)}
+									{getAspectRatioLabel(settings.aspectRatio)}
 									<ChevronDown size={10} />
 								</button>
 							</PopoverTrigger>
@@ -1134,7 +1120,7 @@ export function V4Timeline({
 											type="button"
 											key={ratio}
 											className={`${styles.recMenuRow}${
-												ratio === activeToken ? ` ${styles.active}` : ""
+												ratio === settings.aspectRatio ? ` ${styles.active}` : ""
 											}`}
 											onClick={() => {
 												void setSettings({ aspectRatio: ratio });
@@ -1152,7 +1138,7 @@ export function V4Timeline({
 													type="button"
 													key={format.token}
 													className={`${styles.recMenuRow}${
-														format.token === activeToken ? ` ${styles.active}` : ""
+														format.token === settings.aspectRatio ? ` ${styles.active}` : ""
 													}`}
 													onClick={() => {
 														void setSettings({ aspectRatio: format.token });

src/lib/ai-edition/document/migrate.test.ts

@@ -43,7 +43,7 @@ describe("migrateProjectDataToAxcutDocument", () => {
 	it("produces a v3 document with one asset and one clip from a v2 single-recording project", () => {
 		const doc = migrateProjectDataToAxcutDocument(makeV2Project());
 
-		expect(doc.schemaVersion).toBe(5);
+		expect(doc.schemaVersion).toBe(6);
 		expect(doc.assets).toHaveLength(1);
 		const asset = doc.assets[0];
 		expect(asset.kind).toBe("video");

src/lib/ai-edition/document/outputFormat.test.ts

@@ -225,13 +225,7 @@ describe("pickOutputDims", () => {
 			[asset("a1", 1366, 768), asset("a2", 3840, 2160)],
 			[clip("c1", "a1"), clip("c2", "a2")],
 		);
-		const tokens: AspectRatio[] = [
-			...ASPECT_RATIO_PRESETS,
-			"683:384",
-			"64:27",
-			"1023:767",
-			"native",
-		];
+		const tokens: AspectRatio[] = [...ASPECT_RATIO_PRESETS, "683:384", "64:27", "1023:767"];
 		for (const token of tokens) {
 			const out = pickOutputDims(d, token);
 			expect(out.width % 2, `width for ${token}`).toBe(0);
@@ -256,14 +250,6 @@ describe("pickOutputDims", () => {
 		expect(pickOutputDims(after, "16:9")).toEqual({ width: 3840, height: 2160 });
 	});
 
-	it('legacy "native" still resolves to the reference clip, drift included', () => {
-		const portraitWins = doc(
-			[asset("a1", 1920, 1080), asset("a2", 2160, 3840)],
-			[clip("c1", "a1"), clip("c2", "a2")],
-		);
-		expect(pickOutputDims(portraitWins, "native")).toEqual({ width: 2160, height: 3840 });
-	});
-
 	it("sizes the output off the cropped footprint, not the raw 4K asset", () => {
 		// A single 4K clip cropped to a 16:9 half-width strip: the output must rasterise at the
 		// crop's real size (1920x1080), not the asset's 3840x2160. Before the reference went
@@ -277,18 +263,13 @@ describe("pickOutputDims", () => {
 });
 
 describe("resolveAspectRatioValue", () => {
-	it('resolves legacy "native" against the document instead of the 16/9 fallback', () => {
-		const d = doc([asset("a1", 1080, 1920)], [clip("c1", "a1")]);
-		expect(resolveAspectRatioValue(d, "native")).toBeCloseTo(1080 / 1920, 6);
-	});
-
-	it('falls back to 16/9 for "native" with no document (preview before load)', () => {
-		expect(resolveAspectRatioValue(null, "native")).toBeCloseTo(16 / 9, 6);
-	});
-
+	// The legacy `"native"` AspectRatio is retired — the v5→v6 upgrader (see
+	// `src/lib/ai-edition/schema/index.test.ts` — "v5 -> v6 native AspectRatio
+	// migration") rewrites every stored "native" to a concrete `"W:H"` token at load
+	// time, so by the time this function runs there is no document context to thread
+	// through. What remains is a thin wrapper around `getAspectRatioValue`.
 	it("passes concrete tokens straight through", () => {
-		const d = doc([asset("a1", 1080, 1920)], [clip("c1", "a1")]);
-		expect(resolveAspectRatioValue(d, "4:5")).toBeCloseTo(0.8, 6);
-		expect(resolveAspectRatioValue(d, "64:27")).toBeCloseTo(64 / 27, 6);
+		expect(resolveAspectRatioValue("4:5")).toBeCloseTo(0.8, 6);
+		expect(resolveAspectRatioValue("64:27")).toBeCloseTo(64 / 27, 6);
 	});
 });

src/lib/ai-edition/document/outputFormat.ts

@@ -18,7 +18,6 @@ import { calculateEffectiveSourceDimensions } from "@/lib/exporter/mp4ExportSett
 import {
 	type AspectRatio,
 	getAspectRatioValue,
-	getNativeAspectRatioValue,
 	toAspectRatioToken,
 } from "@/utils/aspectRatioUtils";
 import type { AxcutAsset, AxcutClip, AxcutDocument } from "../schema";
@@ -225,19 +224,13 @@ export function collectNativeFormats(
 }
 
 /**
- * Numeric ratio for a stored selection, with the document available to resolve the legacy
- * `"native"` value. Every consumer that frames or sizes the output must go through this rather
- * than bare `getAspectRatioValue`, which has no document and falls back to 16/9.
+ * Numeric ratio for a stored selection. v6 documents never carry the legacy `"native"`
+ * AspectRatio (the v5→v6 upgrader rewrites it to a concrete `"W:H"` token), so resolution
+ * is a single token lookup. Kept as a function so the preview / export path still has a
+ * single funnel — if storage ever moves, this is the one place to update.
  */
-export function resolveAspectRatioValue(
-	document: AxcutDocument | null | undefined,
-	aspectRatio: AspectRatio,
-	probedAssetDims: Record<string, Dims> = {},
-): number {
-	if (aspectRatio !== "native") return getAspectRatioValue(aspectRatio);
-	if (!document) return getAspectRatioValue("native");
-	const reference = referenceClipDims(document, probedAssetDims);
-	return getNativeAspectRatioValue(reference.width, reference.height);
+export function resolveAspectRatioValue(aspectRatio: AspectRatio): number {
+	return getAspectRatioValue(aspectRatio);
 }
 
 /**
@@ -261,7 +254,7 @@ export function pickOutputDims(
 	probedAssetDims: Record<string, Dims> = {},
 ): Dims {
 	const reference = referenceClipDims(document, probedAssetDims);
-	const ratio = resolveAspectRatioValue(document, aspectRatio, probedAssetDims);
+	const ratio = resolveAspectRatioValue(aspectRatio);
 	const longSide = toEvenPx(Math.max(reference.width, reference.height));
 	if (ratio >= 1) {
 		return { width: longSide, height: toEvenPx(longSide / ratio) };