Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

62.7 KB
Raw Blame
// Vendored from @axcut/schema (https://github.com/EtienneLescot/axcut) —
// original file: packages/axcut-schema/src/index.ts. Modifications for
// OpenScreen's AI-edition merge (Phase 0, see technical-documentation/architecture/document-model.md):
//
//   1. axcutSchemaVersion bumped 2 -> 3.
//   2. clip.sourceEndSec made optional (duration is unknown until asset is probed).
//   3. documentSchema gains annotations[], zoomRanges[], legacyEditor envelopes
//      so OpenScreen's existing regions + appearance settings survive the merge.
//
// ponytail: this exists as the SSOT project model. Phase 0 only touches the
// shape — runtime ops, IPC, and exporter integration land in Phase 1+.

import { z } from "zod";
// Cycle-safe: `aspectRatioUtils` has no schema dependency, and `document/outputFormat`
// is downstream of schema. We import the leaf tokeniser directly so the v5→v6 upgrader
// can rewrite `"native"` without dragging in the whole output-format module.
// Relative, not `@/`: the Electron main bundle imports this module and
// vite-plugin-electron builds it without the root resolve.alias.
import { toAspectRatioToken } from "../../../utils/aspectRatioUtils";
import { LAYOUT_PRESETS } from "../../layoutTypes";
import { clampToBound } from "../../projectDefaults";
// Cycle-safe: `document/ids` only pulls `uuid`, and `timeline/timelineMap`'s
// transitive value-imports (region-ventilation, virtual-preview) import from this
// module TYPE-ONLY, so requiring them here never re-enters schema at runtime.
import { createId } from "../document/ids";
import { materializeLayouts } from "../document/layout";
import { anchorRegionsWithDerivedMs } from "../timeline/timelineMap";

//   4. v5 — modifiers (zoom / annotation / speed / cameraFullscreen) become
//      CLIP-ANCHORED fragments: `{clipId, sourceStartSec, sourceEndSec}` is the
//      source of truth, `startMs`/`endMs` stay as a derived cache for the
//      transition. See technical-documentation/architecture/timeline-model.md
//   5. v6 — `"native"` AspectRatio is retired OPPORTUNISTICALLY. The v5→v6
//      upgrader rewrites a stored `"native"` to a concrete `"W:H"` token from
//      the timeline's largest clip, but only when the source dimensions are
//      actually known; otherwise it leaves the sentinel, which keeps resolving
//      dynamically at runtime. See `upgradeV5DocumentToV6` for why guessing
//      would corrupt v1.7 imports.
//   6. v7 — trims join the v5 clip anchor: `AxcutTrimRange` gains `clipId`.
//      They were the last region kind still addressed by `assetId` alone, which
//      made them AMBIGUOUS the moment two clips drew from the same asset (a
//      duplicated clip): every reader either matched both clips or picked the
//      first. See `upgradeV6DocumentToV7`.
//   7. v8 — Auto becomes the default AspectRatio. A document that never chose a
//      ratio stores none and reads the default, so the upgrader pins the one it
//      has always shown, 16:9. See `upgradeV7DocumentToV8`.
//   8. v9 — layoutRegions replaces Full Camera with a typed layout partition.
//      Legacy camera envelopes are migrated once, preserving their original easing.
export const axcutSchemaVersion = 9;

// ponytail: every region schema shares the same monotonicity rule
// (end >= start) with the same error shape. Factor the refine so the
// five call sites stay declarative; the message + path stay tied to
// the field names (e.g. `endSec >= startSec`, `endMs >= startMs`).
const endGteStart = <T extends z.ZodObject<z.ZodRawShape>>(
	schema: T,
	endKey: keyof T["shape"] & string,
	startKey: keyof T["shape"] & string,
) =>
	schema.refine((data) => (data[endKey] as number) >= (data[startKey] as number), {
		message: `${endKey} must be greater than or equal to ${startKey}`,
		path: [endKey],
	});

export const isoDateSchema = z.string().datetime({ offset: true });

export const wordSchema = z
	.object({
		id: z.string().min(1),
		segmentId: z.string().min(1),
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
		text: z.string(),
		// Provenance of the TEXT, so a hand-corrected word can be told from a
		// transcribed one. Both fields are additive and absent on every document
		// written before them (like `cameraTrack.width`), so no schema bump: an
		// older build simply drops them on save.
		//
		// `document/transcript.ts` is the only writer, and it keeps the pair
		// consistent: `originalText` is set from the ASR text the first time a user
		// rewrites the word and never overwritten afterwards, so it stays the revert
		// target however many times the word is edited; typing the original back
		// clears both, which IS the revert.
		//
		// Absent `source` means the word came from the transcriber. It is what makes
		// a re-transcription able to carry the user's corrections forward
		// (`carryOverWordEdits`) instead of silently discarding them — and what a
		// future TTS pass will read to know which words it has to speak.
		originalText: z.string().optional(),
		source: z.enum(["asr", "user", "synth"]).optional(),
	})
	.refine((data) => data.endSec >= data.startSec, {
		message: "endSec must be greater than or equal to startSec",
		path: ["endSec"],
	});

export const transcriptSegmentSchema = z
	.object({
		id: z.string().min(1),
		kind: z.enum(["speech", "silence"]),
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
		text: z.string(),
		wordIds: z.array(z.string().min(1)).default([]),
	})
	.refine((data) => data.endSec >= data.startSec, {
		message: "endSec must be greater than or equal to startSec",
		path: ["endSec"],
	});

export const transcriptSchema = z.object({
	assetId: z.string().min(1),
	language: z.string().min(1),
	sourceDslPath: z.string().optional(),
	sourceJsonPath: z.string().optional(),
	segments: z.array(transcriptSegmentSchema).default([]),
	words: z.array(wordSchema).default([]),
});

export const assetVideoSchema = z.object({
	codec: z.string().default("unknown"),
	width: z.number().int().nonnegative().default(0),
	height: z.number().int().nonnegative().default(0),
	fps: z.number().nonnegative().default(0),
});

export const assetAudioSchema = z.object({
	codec: z.string().default("unknown"),
	sampleRate: z.number().int().nonnegative().default(0),
	channels: z.number().int().nonnegative().default(0),
});

// ponytail: the webcam is a derived stream — it is NOT edited. Cut / zoom /
// speed live on the main timeline and apply to the camera as a render of the
// same source-time progression. Source path comes from the recording
// session sidecar (auto-linked when an asset is imported from a recording).
// `offsetMs` accounts for the camera starting before/after the screen.
//
// Lives on the asset (not the document) since P4 (per-asset media links) —
// a project can hold multiple assets, each recorded with its own camera (or
// none). See technical-documentation/architecture/document-model.md.
export const cameraTrackSchema = z
	.object({
		sourcePath: z.string().min(1),
		startMs: z.number().nonnegative().default(0),
		offsetMs: z.number().int().default(0),
		visible: z.boolean().default(true),
		// The camera file's real pixel dimensions, the camera's answer to
		// `assetVideoSchema.width/height` for the screen. The layout box for the PiP is
		// derived from them, and without them it falls back to a hardcoded 4:3 — which is
		// how a 16:9 camera came out framed one way in the preview (where a mounted
		// <video> had reported its size) and another way in an export (where none had).
		//
		// Optional and absent on every document written before this, exactly like
		// `transcriptionFailure` below: additive, so no schema-version bump, and an older
		// build simply drops the key on save. The fallback stays for that window.
		width: z.number().int().positive().optional(),
		height: z.number().int().positive().optional(),
	})
	.nullable()
	.default(null);

// Why a media can never be transcribed. Only the DETERMINISTIC verdicts live
// here: a container with no audio track (a screen recording captured with no
// mic and no system audio — the common case) fails identically on every
// attempt, and re-deciding that costs a full audio extraction on each project
// open. Transient failures (engine down, decode hiccup) are deliberately NOT
// persistable and stay in the transcription store for the session, so the next
// load retries them. See `src/lib/ai-edition/transcription/status.ts`.
export const assetTranscriptionFailureSchema = z.object({
	kind: z.enum(["no-audio", "unsupported-audio"]),
	message: z.string().default(""),
	at: isoDateSchema.optional(),
});

export const assetSchema = z.object({
	id: z.string().min(1),
	// Widened from a `"video"` literal when external-audio import landed (issue
	// #350). An imported voiceover / BGM / SFX file carries no video stream, so it
	// needs its own kind; every document written before this only ever held
	// `"video"`, which still validates, so the widening is additive (no
	// schemaVersion bump — same rule as `transcriptionFailure` below).
	kind: z.enum(["video", "audio"]).default("video"),
	label: z.string().min(1),
	originalPath: z.string().min(1),
	proxyPath: z.string().optional(),
	waveformPath: z.string().optional(),
	durationSec: z.number().nonnegative().optional(),
	// P3.1 — file size captured at import time (fs.stat in document-service).
	sizeBytes: z.number().int().nonnegative().optional(),
	video: assetVideoSchema.optional(),
	audio: assetAudioSchema.optional(),
	// Absent on every document written before auto-transcription; additive, so
	// no schema-version bump (an older build simply drops the key on save).
	transcriptionFailure: assetTranscriptionFailureSchema.nullish(),
	cameraTrack: cameraTrackSchema,
});

// A crop is a sub-rectangle of the source video, expressed as fractions
// (0-1) of its full frame. Lives on the clip (not the document/legacyEditor
// envelope) since a crop frames one specific piece of footage — two clips
// cut from the same or different assets can reasonably want different
// framings. Mirrors `CropRegion` in `src/components/video-editor/types.ts`;
// duplicated here so the schema package has no dependency on the React
// editor module (same rationale as AnnotationRegion/ZoomRegion above).
export const clipCropRegionSchema = z.object({
	x: z.number().min(0).max(1),
	y: z.number().min(0).max(1),
	width: z.number().min(0).max(1),
	height: z.number().min(0).max(1),
});

export const clipSchema = z
	.object({
		id: z.string().min(1),
		assetId: z.string().min(1),
		sourceStartSec: z.number().nonnegative(),
		// ponytail: optional because v2 migrations have unknown asset duration at
		// migration time. The renderer fills this in once StreamingVideoDecoder probes
		// the file (Phase 1+).
		sourceEndSec: z.number().nonnegative().optional(),
		timelineStartSec: z.number().nonnegative(),
		timelineEndSec: z.number().nonnegative(),
		wordRefs: z.array(z.string().min(1)).default([]),
		origin: z.enum(["system", "agent", "user"]),
		reason: z.string().default(""),
		// Absent/undefined means "no crop" (full frame) — callers should treat
		// that as the identity region {x:0,y:0,width:1,height:1} rather than
		// storing the identity explicitly, so untouched clips stay lean.
		cropRegion: clipCropRegionSchema.optional(),
	})
	.refine((data) => data.timelineEndSec >= data.timelineStartSec, {
		message: "timelineEndSec must be greater than or equal to timelineStartSec",
		path: ["timelineEndSec"],
	})
	.refine((data) => data.sourceEndSec === undefined || data.sourceEndSec >= data.sourceStartSec, {
		message: "sourceEndSec must be greater than or equal to sourceStartSec",
		path: ["sourceEndSec"],
	});

export const gapSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		timelineStartSec: z.number().nonnegative(),
		timelineEndSec: z.number().nonnegative(),
		reason: z.string().default(""),
	}),
	"timelineEndSec",
	"timelineStartSec",
);

export const rangeSchema = endGteStart(
	z.object({
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
		reason: z.string().default(""),
	}),
	"endSec",
	"startSec",
);

// ponytail: trimRanges reference asset source-time (not timeline). trimRegions
// in v2 are the inverse — a skip = the region inside the source we DON'T keep.
//
// `startSec`/`endSec` ARE the source range of `clipAnchorShape` under their older
// names, so a trim needs only `clipId` to become a complete v5 clip anchor. Optional
// for the same reason it is on the other kinds: a trim that could not be anchored
// (`upgradeV6DocumentToV7`) is kept, not dropped, and falls back to the historical
// asset-wide matching. Everything that asks "does this trim apply to this clip?" must
// go through `trimAppliesToClip` (timeline/trim-mapping) so the two rules stay one rule.
export const trimRangeSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		assetId: z.string().min(1),
		clipId: z.string().min(1).optional(),
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
		reason: z.string().default(""),
		origin: z.enum(["system", "agent", "user"]),
	}),
	"endSec",
	"startSec",
);

export const timelineSchema = z.preprocess(
	// Back-compat: the field was renamed skipRanges → trimRanges. Old persisted
	// documents (disk + browser-shim localStorage) still carry `skipRanges`;
	// fold it into `trimRanges` on load so trims aren't silently dropped.
	(value) => {
		if (value && typeof value === "object" && !Array.isArray(value)) {
			const v = value as Record<string, unknown>;
			if (v.skipRanges !== undefined && v.trimRanges === undefined) {
				return { ...v, trimRanges: v.skipRanges };
			}
		}
		return value;
	},
	z.object({
		clips: z.array(clipSchema).default([]),
		gaps: z.array(gapSchema).default([]),
		trimRanges: z.array(trimRangeSchema).default([]),
		// Additive, like every optional field before it: absent on every document written
		// before this, so no schema bump — an older build simply drops the key on save, and
		// the words it belonged to keep their text and lose only their pause.
		muteRanges: z.array(rangeSchema).default([]),
		speedRanges: z.array(rangeSchema).default([]),
		captionRanges: z.array(rangeSchema).default([]),
	}),
);

export const timelineOperationSchema = z.discriminatedUnion("type", [
	z.object({
		type: z.literal("replace_timeline"),
		reason: z.string().default(""),
		intervals: z
			.array(z.object({ startSec: z.number().nonnegative(), endSec: z.number().nonnegative() }))
			.default([]),
	}),
	z.object({
		type: z.literal("drop_range"),
		reason: z.string().default(""),
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
	}),
	z.object({
		type: z.literal("drop_word_range"),
		reason: z.string().default(""),
		startWordId: z.string().min(1),
		endWordId: z.string().min(1),
	}),
	z.object({
		type: z.literal("add_trim_range"),
		reason: z.string().default(""),
		assetId: z.string().min(1),
		// Which clip the cut was authored on. Optional so callers that genuinely have no
		// clip context still work, but every UI path knows it — without it a trim on the
		// second clip of a duplicated asset is indistinguishable from one on the first.
		clipId: z.string().min(1).optional(),
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
	}),
	z.object({
		type: z.literal("update_trim_range"),
		reason: z.string().default(""),
		trimRangeId: z.string().min(1),
		startSec: z.number().nonnegative(),
		endSec: z.number().nonnegative(),
	}),
	z.object({
		type: z.literal("remove_trim_range"),
		reason: z.string().default(""),
		trimRangeId: z.string().min(1),
	}),
	z.object({
		type: z.literal("update_clip_range"),
		reason: z.string().default(""),
		clipId: z.string().min(1),
		sourceStartSec: z.number().nonnegative(),
		sourceEndSec: z.number().nonnegative().optional(),
	}),
	z.object({
		type: z.literal("duplicate_clip"),
		reason: z.string().default(""),
		clipId: z.string().min(1),
	}),
	z.object({
		type: z.literal("move_clip"),
		reason: z.string().default(""),
		clipId: z.string().min(1),
		// ponytail: `insertIndex`, matching the ONE implementation
		// (`AxcutTimelineOperation` in document/operations.ts, applied by
		// `applyTimelineOperation`). This schema declared `timelineStartSec`
		// instead — a second, incompatible contract for the same op name, with no
		// importer anywhere to notice. Whoever wired the two together next would
		// have had a parse that accepted what the dispatcher could not run.
		insertIndex: z.number().int().nonnegative(),
	}),
	z.object({
		type: z.literal("insert_asset_clip"),
		reason: z.string().default(""),
		assetId: z.string().min(1),
		beforeClipId: z.string().min(1).nullable(),
		afterClipId: z.string().min(1).nullable(),
		sourceStartSec: z.number().nonnegative(),
		sourceEndSec: z.number().nonnegative().optional(),
	}),
	z.object({
		type: z.literal("restore_full_timeline"),
		reason: z.string().default(""),
	}),
]);

// OpenScreen additions to the axcut document. Mirrors src/components/video-editor/types.ts
// (AnnotationRegion / ZoomRegion) — duplicated here so the schema package has no
// dependency on the React editor module.

export const blurDataSchema = z
	.object({
		type: z.enum(["blur", "mosaic"]).default("mosaic"),
		shape: z.enum(["rectangle", "oval", "freehand"]).default("rectangle"),
		color: z.enum(["white", "black"]).default("white"),
		intensity: z.number().nonnegative().default(12),
		blockSize: z.number().nonnegative().default(12),
		freehandPoints: z
			.array(z.object({ x: z.number().nonnegative(), y: z.number().nonnegative() }))
			.optional(),
	})
	.optional();

export const figureDataSchema = z
	.object({
		arrowDirection: z
			.enum(["up", "down", "left", "right", "up-right", "up-left", "down-right", "down-left"])
			.default("right"),
		color: z.string().default("#34B27B"),
		strokeWidth: z.number().nonnegative().default(4),
	})
	.optional();

const annotationStyleSchema = z.object({
	color: z.string().default("#ffffff"),
	backgroundColor: z.string().default("transparent"),
	// `backgroundColor: "transparent"` is how every renderer reads "no background", so switching
	// the background off has to overwrite the colour the user picked — and switching it back on had
	// nothing left to restore, which is why it always came back black. This keeps that last colour
	// so the toggle is reversible. Nothing renders it: the paint path still reads `backgroundColor`
	// alone.
	lastBackgroundColor: z.string().optional(),
	// Read into its bound rather than refused: a size of 0, which an emptied field used to store,
	// must still open, as the smallest text instead of none.
	fontSize: z
		.number()
		.default(32)
		.transform((size) => clampToBound(size, "annotationFontSize")),
	fontFamily: z.string().default("Inter"),
	fontWeight: z.enum(["normal", "bold"]).default("bold"),
	fontStyle: z.enum(["normal", "italic"]).default("normal"),
	textDecoration: z.enum(["none", "underline"]).default("none"),
	textAlign: z.enum(["left", "center", "right"]).default("center"),
	textAnimation: z
		.enum(["none", "fade", "rise", "pop", "slide-left", "typewriter", "pulse"])
		.optional(),
});

// v5 clip anchor — the source of truth for a modifier's position. A region the user drew
// across a clip boundary is stored as one fragment per covered clip; they need no shared
// marker, because two regions with equal properties that touch render as one pill by the
// universal merge rule (see timelineMap). Optional during the Stage B transition: the
// v4→v5 migration fills it in, and regions created by not-yet-migrated code still validate
// on startMs/endMs alone, which remain a DERIVED cache of the fragment's ruler span.
const clipAnchorShape = {
	clipId: z.string().min(1).optional(),
	sourceStartSec: z.number().nonnegative().optional(),
	sourceEndSec: z.number().nonnegative().optional(),
};

export const annotationRegionSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		startMs: z.number().nonnegative(),
		endMs: z.number().nonnegative(),
		...clipAnchorShape,
		type: z.enum(["text", "image", "figure", "blur"]),
		content: z.string().default(""),
		textContent: z.string().optional(),
		imageContent: z.string().optional(),
		// The box `position`, `size` and the text size are measured against. `"frame"`, the output
		// frame: where text, images and arrows are placed, so padding and the footage's size never
		// move them. Absent, the footage (screen rect): a privacy blur always, since it must stay on
		// what it hides, and every annotation saved before frame placement existed. See
		// `annotations/placement.ts`.
		space: z.literal("frame").optional(),
		// At least 0 too, except for an arrow: see the refine below.
		position: z.object({
			x: z.number().max(100),
			y: z.number().max(100),
		}),
		size: z.object({
			width: z.number().positive(),
			height: z.number().positive(),
		}),
		style: annotationStyleSchema,
		zIndex: z.number().int().nonnegative(),
		annotationSource: z.literal("auto-caption").optional(),
		figureData: figureDataSchema,
		blurData: blurDataSchema,
	}),
	"endMs",
	"startMs",
).refine(
	// The compositor draws an arrow in the middle of its square box, so an arrow drawn against the
	// frame's left or top edge has a box that starts before the frame (`annotations/arrowBounds.ts`).
	// Its strokes stay inside. Every other box starts inside the frame.
	(region) => region.type === "figure" || (region.position.x >= 0 && region.position.y >= 0),
	{ message: "position must be at least 0", path: ["position"] },
);

export const zoomRegionSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		startMs: z.number().nonnegative(),
		endMs: z.number().nonnegative(),
		...clipAnchorShape,
		depth: z.union([
			z.literal(1),
			z.literal(2),
			z.literal(3),
			z.literal(4),
			z.literal(5),
			z.literal(6),
		]),
		focus: z.object({
			cx: z.number().min(0).max(1),
			cy: z.number().min(0).max(1),
		}),
		focusMode: z.enum(["manual", "auto"]).optional(),
		/** The zoom's 3D camera (`Rotation3DPreset` in `components/video-editor/types.ts` — same
		 *  literal list, duplicated here): a fixed angle, or the camera that orbits the screen
		 *  (`crates/compositor/src/camera.rs`), placed by the zoom's focus mode. Absent means a flat
		 *  screen. A stored `iso`, the retired "turned left, seen from above" angle, reads as
		 *  `left`, which kept its look (`readRotation3DPreset`): every document load goes through
		 *  this parse. A stored `follow-cursor` never reaches it (`readFollowCursorAsAutoOrbit`). */
		rotationPreset: z
			.enum(["iso", "left", "right", "orbit"])
			.transform((preset) => (preset === "iso" ? "left" : preset))
			.optional(),
		customScale: z.number().positive().optional(),
		source: z.enum(["auto", "manual"]).optional(),
		hideCursor: z.boolean().optional(),
	}),
	"endMs",
	"startMs",
);

// Agent-written shader effects (docs/shader-effects.md, B). A definition carries the WGSL and its
// declared parameters; a range poses it on the timeline, clip-anchored like a zoom, with its own
// parameter values. Additive: a document written before these existed loads unchanged.
const shaderEffectParamName = z.string().regex(/^[a-z][a-z0-9_]{0,31}$/);
const shaderEffectColor = z.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
const shaderEffectPoint = z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) });
// Written by the agent, in the user's language, shown as-is: content, not interface copy.
const shaderEffectLabel = z.string().max(40).default("");

export const shaderEffectParamSchema = z.discriminatedUnion("type", [
	z.object({
		type: z.literal("number"),
		name: shaderEffectParamName,
		label: shaderEffectLabel,
		default: z.number(),
		min: z.number(),
		max: z.number(),
	}),
	z.object({
		type: z.literal("toggle"),
		name: shaderEffectParamName,
		label: shaderEffectLabel,
		default: z.boolean(),
	}),
	z.object({
		type: z.literal("color"),
		name: shaderEffectParamName,
		label: shaderEffectLabel,
		default: shaderEffectColor,
	}),
	z.object({
		type: z.literal("point"),
		name: shaderEffectParamName,
		label: shaderEffectLabel,
		default: shaderEffectPoint,
	}),
]);

export const shaderEffectValueSchema = z.union([
	z.number(),
	z.boolean(),
	shaderEffectColor,
	shaderEffectPoint,
]);

export const shaderEffectSchema = z
	.object({
		id: z.string().min(1),
		// What the pill shows.
		name: z.string().min(1).max(60),
		// For the next agent: what the effect does, in one sentence.
		description: z.string().max(500).default(""),
		// The WGSL contract version. Not a literal: a version this build does not know (written by
		// a newer one) must still load; the compositor leaves its regions undrawn.
		contract: z.number().int().positive(),
		code: z.string().min(1).max(65_536),
		// The `max` here is a technical ceiling, not a budget: see the cost tiers.
		params: z.array(shaderEffectParamSchema).max(32).default([]),
		origin: z.enum(["agent", "user"]).default("agent"),
		// The compositor's cost estimate, cached when the code was last checked. Derived, never an
		// input: `frameReads` is `frame()` reads per pixel, `tier` its indicative tier.
		cost: z
			.object({
				tier: z.enum(["light", "medium", "heavy", "very-heavy"]),
				frameReads: z.number().nonnegative(),
			})
			.optional(),
	})
	.superRefine((effect, ctx) => {
		const names = new Set<string>();
		for (const [index, param] of effect.params.entries()) {
			if (names.has(param.name)) {
				ctx.addIssue({
					code: "custom",
					message: `parameter "${param.name}" is declared twice`,
					path: ["params", index],
				});
			}
			names.add(param.name);
			if (param.type === "number" && !(param.min <= param.default && param.default <= param.max)) {
				ctx.addIssue({
					code: "custom",
					message: `parameter "${param.name}": min ≤ default ≤ max`,
					path: ["params", index],
				});
			}
		}
	});

export const shaderEffectRangeSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		startMs: z.number().nonnegative(),
		endMs: z.number().nonnegative(),
		...clipAnchorShape,
		effectId: z.string().min(1),
		// Only the values that differ from the definition's defaults.
		values: z.record(z.string(), shaderEffectValueSchema).default({}),
		// What the effect transforms: the picture under the texts, the texts alone, or both.
		target: z.enum(["image", "text", "both"]).default("image"),
	}),
	"endMs",
	"startMs",
);

// External audio import (issue #350) — voiceover / BGM / SFX layered over the
// programme. Unlike zoom/speed/annotation/trim, an audio track is NOT
// clip-anchored: it floats over the whole timeline, addressed in RAW/document
// timeline seconds — the same clock the ruler, playhead and clip
// `timelineStartSec`/`timelineEndSec` use, and the one `addAudioTrack` seeds from
// the playhead. The preview positions the track on exactly this clock (see
// `resolveTimelineAudioPlayback` in VirtualPreview). The export's OUTPUT programme
// is trim-compressed, so the renderer maps this position to output time when
// building the scene — an identity map when the project has no trims/speed (the
// common case), an accepted approximation otherwise, the same way the preview
// approximates trims by re-seeking. See `SceneAudioTrack` (sceneDescription.ts,
// audio.rs).
//
// `assetId` points at an asset with `kind: "audio"`. `timelineStartSec` places
// the track's head; `trimStartSec`/`trimEndSec` window the source file (both in
// source seconds); `gainDb` sets its level.
// An imported or recorded audio track (voiceover / BGM / SFX) placed on the
// timeline (issue #350).
//
// CLIP-ANCHORED, on the same v5 contract as zoom/annotation: `{clipId,
// sourceStartSec, sourceEndSec}` is the source of truth and `startMs`/`endMs`
// is a derived ruler cache, so a track travels with the content it was placed
// over instead of sitting still while a reorder or trim slides the programme
// underneath it. Positions are RAW ruler ms; the export projects them onto the
// trim-compressed programme (`projectRawTimelineSecToPlayback`).
//
// `offsetMs` skips INTO the source file — start the music at its chorus. It
// replaces #502's `trimStartSec`/`trimEndSec` pair: the track's own span
// (`startMs`..`endMs`) is where it plays, so the tail trim is implied by the
// span and does not need storing twice. A file longer than its span is cut off
// at the span unless `loop` is set, in which case it repeats.
//
// The anchor ventilates one user-visible track into one fragment PER CLIP it
// covers. Fragments of the same track share `trackId`, and each carries its own
// `offsetMs` advanced by the source time its predecessors consumed — see
// `anchorAudioTrackFragments`. Without that every fragment would restart the
// file at the same offset and re-run the fades, so a bed spanning a cut would
// audibly restart at the boundary.
export const audioTrackSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		// Shared by every fragment of one user-visible track: what the lane draws
		// as a single pill, what the inspector edits, and what delete removes.
		// Absent on tracks written before ventilation existed — they are their own
		// single fragment, so `trackId ?? id` is always the group key.
		trackId: z.string().min(1).optional(),
		startMs: z.number().nonnegative(),
		endMs: z.number().nonnegative(),
		...clipAnchorShape,
		assetId: z.string().min(1),
		kind: z.enum(["voiceover", "music"]).default("music"),
		// Full source duration of the underlying file, cached here so the timeline
		// can lay out the pill before the asset is re-probed on load.
		durationSec: z.number().nonnegative().default(0),
		offsetMs: z.number().int().nonnegative().default(0),
		gainDb: z.number().min(-60).max(12).default(0),
		loop: z.boolean().default(false),
		fadeInMs: z.number().int().nonnegative().default(0),
		fadeOutMs: z.number().int().nonnegative().default(0),
		muted: z.boolean().default(false),
		label: z.string().default(""),
		origin: z.enum(["system", "agent", "user"]).default("user"),
	}),
	"endMs",
	"startMs",
);

// Legacy OpenScreen appearance / export settings that the v3 schema doesn't
// normalize into the timeline / assets model. They are applied at export time
// by the existing pipeline (see technical-documentation/architecture/document-model.md).
//
// ponytail: passthrough blob — v2 ProjectEditorState carries ~25 fields, several
// of which (autoZoomEnabled, autoFocusAll, cursorTheme, …) have no first-class
// home yet. Phase 1 timeline rewrite + Phase 9 settings sync will tighten this.
// Round-trip through the migration must be lossless for now.
export const legacyEditorSchema = z.object({}).passthrough().nullable().default(null);

export const layoutRegionSchema = endGteStart(
	z.object({
		id: z.string().min(1),
		startMs: z.number().nonnegative(),
		endMs: z.number().nonnegative(),
		...clipAnchorShape,
		preset: z.enum(LAYOUT_PRESETS),
		legacyCamera: z
			.object({
				basePreset: z.enum(LAYOUT_PRESETS),
				envelopes: z.array(
					endGteStart(
						z.object({
							sourceStartSec: z.number().nonnegative(),
							sourceEndSec: z.number().nonnegative(),
						}),
						"sourceEndSec",
						"sourceStartSec",
					),
				),
			})
			.optional(),
	}),
	"endMs",
	"startMs",
);

const documentSchemaShape = z.object({
	schemaVersion: z.literal(axcutSchemaVersion),
	project: z.object({
		id: z.string().min(1),
		title: z.string().min(1),
		createdAt: isoDateSchema,
		updatedAt: isoDateSchema,
		primaryAssetId: z.string().optional(),
		// Names and terms passed to Whisper as its initial prompt (issue #1023).
		// Additive, so no schemaVersion bump: an older build drops the key on save.
		vocabulary: z.string().optional(),
	}),
	assets: z.array(assetSchema).default([]),
	transcript: transcriptSchema.nullable().default(null),
	transcripts: z.array(transcriptSchema).default([]),
	timeline: timelineSchema.default({
		clips: [],
		gaps: [],
		trimRanges: [],
		muteRanges: [],
		speedRanges: [],
		captionRanges: [],
	}),
	annotations: z.array(annotationRegionSchema).default([]),
	zoomRanges: z.array(zoomRegionSchema).default([]),
	// Agent-written shader effects (docs/shader-effects.md). Optional rather than defaulted, like
	// `vocabulary`: a document without effects carries no trace of them, and every reader treats
	// an absent list as empty. An older build drops both keys when it saves.
	shaderEffects: z.array(shaderEffectSchema).optional(),
	shaderEffectRanges: z.array(shaderEffectRangeSchema).optional(),
	// Imported audio tracks (issue #350). Defaulted so every document written
	// before this loads unchanged; an older build simply strips the key on save.
	audioTracks: z.array(audioTrackSchema).default([]),
	// Absent/empty means one global layout; fragments are materialised on first change.
	layoutRegions: z.array(layoutRegionSchema).optional(),
	legacyEditor: legacyEditorSchema.nullable().default(null),
});

// P4 — v3 documents carried a single project-level `cameraTrack` (one project
// = one camera, inherited from the pre-multi-clip editor). v4 moves it onto
// the owning asset (see `assetSchema.cameraTrack` above) so each asset in a
// multi-clip project can carry its own camera link. This is invoked at LOAD
// TIME by `migrateRawDocumentToCurrent` in `document/migrate.ts`, not at every
// `documentSchema.parse(...)` call (the parse is now a pure v6 validation
// step — see the comment above `documentSchema` below). It does NOT touch v2
// (still handled solely by the separate `migrateProjectDataToAxcutDocument`
// pure function) or reject unknown versions; anything that isn't exactly v3
// passes through unchanged so the caller's `documentSchema.parse` can
// reject it via the `schemaVersion` literal.
export function upgradeV3DocumentToV4(raw: unknown): unknown {
	if (!raw || typeof raw !== "object") return raw;
	const doc = raw as Record<string, unknown>;
	if (doc.schemaVersion !== 3) return raw;

	const legacyCameraTrack = doc.cameraTrack ?? null;
	const assets = Array.isArray(doc.assets) ? doc.assets : [];
	const project = (doc.project ?? {}) as { primaryAssetId?: string };
	const targetAssetId = project.primaryAssetId ?? (assets[0] as { id?: string } | undefined)?.id;

	const nextAssets = assets.map((asset) => {
		if (!asset || typeof asset !== "object") return asset;
		const a = asset as Record<string, unknown>;
		return legacyCameraTrack && a.id === targetAssetId && a.cameraTrack === undefined
			? { ...a, cameraTrack: legacyCameraTrack }
			: a;
	});

	const { cameraTrack: _legacyCameraTrack, ...rest } = doc;
	return { ...rest, schemaVersion: 4, assets: nextAssets };
}

/**
 * v4 → v5 — modifiers become CLIP-ANCHORED fragments. Every RAW-virtual-ms region
 * (document `zoomRanges` / `annotations`, plus the `legacyEditor.speedRegions` /
 * `cameraFullscreenRegions` envelopes) is ventilated across the stored RAW clip
 * layout it was authored against, yielding one fragment per covered clip, with
 * `startMs`/`endMs` re-derived as a transition cache. The fragments carry no marker
 * tying them together: they share the same properties, so the ruler already renders
 * them as one pill whenever they are adjacent (see timelineMap merge rule).
 *
 * A region covering no clip (zero-length, or off the end of the timeline) is
 * dropped: it could never play. A document with no clips has nothing to anchor to,
 * so its regions pass through untouched (still valid — the anchor is optional).
 *
 * Invoked at LOAD TIME by `migrateRawDocumentToCurrent` in `document/migrate.ts`,
 * not at every `documentSchema.parse(...)` call.
 */
export function upgradeV4DocumentToV5(raw: unknown): unknown {
	if (!raw || typeof raw !== "object") return raw;
	const doc = raw as Record<string, unknown>;
	if (doc.schemaVersion !== 4) return raw;

	const timeline = (doc.timeline ?? {}) as Record<string, unknown>;
	const clips = (Array.isArray(timeline.clips) ? timeline.clips : []) as unknown as AxcutClip[];

	const anchor = (value: unknown, prefix: string): unknown => {
		if (!Array.isArray(value) || clips.length === 0) return value;
		return anchorRegionsWithDerivedMs(
			value as Array<{ id: string; startMs: number; endMs: number }>,
			clips,
			() => createId(prefix),
		);
	};

	const legacy =
		doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
			? (doc.legacyEditor as Record<string, unknown>)
			: null;

	return {
		...doc,
		schemaVersion: 5,
		zoomRanges: anchor(doc.zoomRanges, "zoom"),
		annotations: anchor(doc.annotations, "ann"),
		legacyEditor: legacy
			? {
					...legacy,
					...(Array.isArray(legacy.speedRegions)
						? { speedRegions: anchor(legacy.speedRegions, "speed") }
						: {}),
					...(Array.isArray(legacy.cameraFullscreenRegions)
						? { cameraFullscreenRegions: anchor(legacy.cameraFullscreenRegions, "camfull") }
						: {}),
				}
			: doc.legacyEditor,
	};
}

/**
 * Largest raw asset footprint among the timeline's clips. A local copy of the
 * `referenceClipDims` pick from `document/outputFormat` — duplicated here so the schema
 * package doesn't import from a module that itself imports from this one (cycle), and so
 * the upgrader doesn't need the runtime `probedAssetDims` map (it runs at load time, before
 * any asset is probed). Crop IS applied: `"native"` resolved to the *cropped* clip
 * dimensions at runtime (`clipEffectiveDims` → `calculateEffectiveSourceDimensions`),
 * so ignoring it here would silently reframe every cropped project.
 */
/** Mirrors `atLeastEven` in mp4ExportSettings — H.264 4:2:0 rejects odd dims. */
function atLeastEven(value: number): number {
	return Math.max(2, Math.floor(value / 2) * 2);
}

function largestClipDims(doc: Record<string, unknown>): { width: number; height: number } | null {
	const timeline = (doc.timeline ?? {}) as Record<string, unknown>;
	const clips = Array.isArray(timeline.clips) ? timeline.clips : [];
	const assets = Array.isArray(doc.assets) ? doc.assets : [];
	const assetById = new Map<string, Record<string, unknown>>();
	for (const a of assets) {
		if (a && typeof a === "object" && typeof (a as { id?: unknown }).id === "string") {
			assetById.set((a as { id: string }).id, a as Record<string, unknown>);
		}
	}
	let best: { width: number; height: number } | null = null;
	let bestArea = 0;
	for (const clip of clips) {
		if (!clip || typeof clip !== "object") continue;
		const c = clip as Record<string, unknown>;
		const assetId = c.assetId;
		if (typeof assetId !== "string") continue;
		const asset = assetById.get(assetId);
		if (!asset) continue;
		const video = (asset.video ?? {}) as Record<string, unknown>;
		const rawW = typeof video.width === "number" ? video.width : 0;
		const rawH = typeof video.height === "number" ? video.height : 0;
		if (rawW <= 0 || rawH <= 0) continue;
		// Apply the clip's crop, exactly as `calculateEffectiveSourceDimensions`
		// (mp4ExportSettings) does at runtime — including the snap to even pixels,
		// so the reduced token matches the size the encoder is actually handed.
		// "native" meant "the cropped source's shape"; ignoring crop here would
		// bake the wrong ratio into every cropped project.
		const crop = (c.cropRegion ?? {}) as Record<string, unknown>;
		const cropW = typeof crop.width === "number" && crop.width > 0 ? crop.width : 1;
		const cropH = typeof crop.height === "number" && crop.height > 0 ? crop.height : 1;
		const w = atLeastEven(Math.round(rawW * cropW));
		const h = atLeastEven(Math.round(rawH * cropH));
		const area = w * h;
		if (area > bestArea) {
			bestArea = area;
			best = { width: w, height: h };
		}
	}
	return best;
}

/**
 * v5 → v6 — retire the `"native"` AspectRatio. `"native"` was a runtime-only sentinel
 * that resolved to the timeline's largest clip; v6 makes that resolution permanent by
 * baking the concrete `"W:H"` token into the document. The new value matches the OLD
 * runtime answer (largest clip), so projects migrate losslessly — preview and export
 * will keep framing the same shape they did yesterday.
 *
 * Falls back to `"16:9"` when the timeline has no clips with known dimensions (the same
 * value the runtime bridge in `resolveAspectRatioValue` returned when no document was
 * available). A document without a `legacyEditor` envelope is unchanged apart from the
 * version bump.
 */
function upgradeV5DocumentToV6(raw: unknown): unknown {
	if (!raw || typeof raw !== "object") return raw;
	const doc = raw as Record<string, unknown>;
	if (doc.schemaVersion !== 5) return raw;

	const legacy =
		doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
			? (doc.legacyEditor as Record<string, unknown>)
			: null;

	if (!legacy || legacy.aspectRatio !== "native") {
		return { ...doc, schemaVersion: 6 };
	}

	// OPPORTUNISTIC, never forced. Baking requires real source dimensions, and a
	// project imported from v1.7 has none yet: `migrateProjectDataToAxcutDocument`
	// builds its asset from `{version:2, media, editor}`, which carries only file
	// paths — dimensions arrive later, when `useTimeline`'s probe effect writes
	// `asset.video` back to disk.
	//
	// So when dimensions are unknown we leave `"native"` in place rather than
	// stamping a hardcoded ratio. `"native"` keeps resolving dynamically at runtime
	// (`resolveAspectRatioValue`), which IS the v1.7 behaviour, and the next load
	// after the probe has persisted dimensions converts it for real. Forcing
	// `"16:9"` here would permanently reframe every portrait v1.7 project that used
	// "Native", on its first open in v1.8, with no way back.
	const dims = largestClipDims(doc);
	if (!dims) {
		return { ...doc, schemaVersion: 6 };
	}
	return {
		...doc,
		schemaVersion: 6,
		legacyEditor: { ...legacy, aspectRatio: toAspectRatioToken(dims.width, dims.height) },
	};
}

/**
 * v6 → v7 — trims become CLIP-ANCHORED, the last region kind that wasn't.
 *
 * A v6 trim says only "this source span of this asset is cut". That is unambiguous while
 * one asset backs one clip, and ambiguous the moment it doesn't: with two clips over the
 * same media every reader had to guess, and each guessed differently — the transcript pane
 * showed the cut on BOTH clips, the ruler drew it on the FIRST, and playback/export removed
 * the span from BOTH. Anchoring the trim to the clip it was authored on removes the guess.
 *
 * The upgrade VENTILATES rather than picks: a stored trim is replaced by one anchored entry
 * per clip it currently covers, each clamped to that clip's source window. That is a
 * faithful restatement of what the document already renders (a v6 trim really did cut every
 * clip of its asset), so nothing about the output moves — but the entries are now separately
 * addressable, which is what lets a user delete the copy on the clip they didn't mean.
 * Mirrors `upgradeV4DocumentToV5`, which ventilated the other kinds the same way.
 *
 * A trim covering no clip is kept UNCHANGED rather than dropped — never lose user data.
 * `replaceTimeline` mints exactly such trims (the inverted kept-intervals lie outside every
 * clip by construction), and a document with no clips has nothing to anchor against.
 * Un-anchored trims keep the v6 asset-wide behaviour via `trimAppliesToClip`.
 */
export function upgradeV6DocumentToV7(raw: unknown): unknown {
	if (!raw || typeof raw !== "object") return raw;
	const doc = raw as Record<string, unknown>;
	if (doc.schemaVersion !== 6) return raw;

	const timeline =
		doc.timeline && typeof doc.timeline === "object" && !Array.isArray(doc.timeline)
			? (doc.timeline as Record<string, unknown>)
			: null;
	const trims = timeline && Array.isArray(timeline.trimRanges) ? timeline.trimRanges : null;
	const clips = (timeline && Array.isArray(timeline.clips)
		? timeline.clips
		: []) as unknown as AxcutClip[];
	if (!timeline || !trims || clips.length === 0) return { ...doc, schemaVersion: 7 };

	const anchored = trims.flatMap((entry) => {
		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [entry];
		const trim = entry as Record<string, unknown>;
		// Already anchored (a re-run, or a doc written by a mixed-version chain): leave it.
		if (typeof trim.clipId === "string") return [trim];
		if (typeof trim.assetId !== "string") return [trim];
		if (typeof trim.startSec !== "number" || typeof trim.endSec !== "number") return [trim];
		const lo = Math.min(trim.startSec, trim.endSec);
		const hi = Math.max(trim.startSec, trim.endSec);

		const fragments = clips.flatMap((clip) => {
			// `clips` is raw, untrusted input at this point (the schema parse runs after the
			// upgrade chain), so a malformed entry must not take the whole project load down.
			if (!clip || typeof clip !== "object" || typeof clip.id !== "string") return [];
			if (clip.assetId !== trim.assetId) return [];
			const clipEnd = clip.sourceEndSec ?? clip.sourceStartSec;
			// An unprobed clip has no real window yet; anchoring against it would clamp the
			// trim to nothing. Leave those to the un-anchored fallback (same reasoning as
			// `rederiveRegionMs`, which refuses to clamp against an unprobed window).
			if (clipEnd <= clip.sourceStartSec) return [];
			const startSec = Math.max(lo, clip.sourceStartSec);
			const endSec = Math.min(hi, clipEnd);
			if (endSec <= startSec) return [];
			return [{ ...trim, clipId: clip.id, startSec, endSec }];
		});
		if (fragments.length === 0) return [trim];
		// The first fragment keeps the original id, so ids already held elsewhere (an undo
		// entry, an in-flight `removeTrim`) still resolve; extras get fresh ones.
		return fragments.map((f, i) => (i === 0 ? f : { ...f, id: createId("trim") }));
	});

	return { ...doc, schemaVersion: 7, timeline: { ...timeline, trimRanges: anchored } };
}

/**
 * v7 → v8 — Auto becomes the default AspectRatio, and older documents keep their frame.
 *
 * A project whose user never opened the ratio menu stores no `aspectRatio` at all: every
 * reader falls back to the default (`getEditorSettings`). Changing that default would
 * therefore reshape every such project on its next open, which is the silent drift v6
 * removed for `"native"`. So the value those documents have always shown, 16:9, is written
 * down; only documents created from v8 on take the new default.
 *
 * Mirrors the read: `getEditorSettings` takes any stored value as is, so only a missing one
 * (no envelope, or no key) is pinned.
 */
export function upgradeV7DocumentToV8(raw: unknown): unknown {
	if (!raw || typeof raw !== "object") return raw;
	const doc = raw as Record<string, unknown>;
	if (doc.schemaVersion !== 7) return raw;

	const legacy =
		doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
			? (doc.legacyEditor as Record<string, unknown>)
			: null;
	if (legacy?.aspectRatio != null) return { ...doc, schemaVersion: 8 };
	return { ...doc, schemaVersion: 8, legacyEditor: { ...legacy, aspectRatio: "16:9" } };
}

/**
 * Runs the whole upgrade chain on a raw, untrusted value. Idempotent: each step
 * is gated on an exact `schemaVersion`, so an already-current document passes
 * through untouched.
 *
 * Lives here rather than in `document/migrate.ts` on purpose — the Electron main
 * process imports this composer, and `migrate.ts` pulls a value import
 * (`PROJECT_VERSION`) through the `@/` alias, which `vite-plugin-electron` does
 * not configure for the main bundle. Keep this module alias-free.
 */
export function upgradeV8DocumentToV9(raw: unknown): unknown {
	if (!raw || typeof raw !== "object") return raw;
	const doc = raw as AxcutDocument & { schemaVersion: number };
	if (Number(doc.schemaVersion) !== 8) return raw;
	const legacy = doc.legacyEditor ?? {};
	if (!Array.isArray(doc.timeline?.clips)) return { ...doc, schemaVersion: 9 };
	const { cameraFullscreenRegions, ...appearance } = legacy;
	return {
		...doc,
		schemaVersion: 9,
		...(Array.isArray(cameraFullscreenRegions) && cameraFullscreenRegions.length
			? { layoutRegions: materializeLayouts(doc) }
			: {}),
		legacyEditor:
			Array.isArray(doc.layoutRegions) && appearance.aspectRatio == null
				? { ...appearance, aspectRatio: "16:9" }
				: doc.legacyEditor == null
					? null
					: appearance,
	};
}

/**
 * Drop the ghost trims commit `b9e0f1ff` wrote (issue #560).
 *
 * That build let the transcript pane author a cut from the voiceover lane while still
 * anchoring it on whatever the words belonged to — an AUDIO asset and an audio fragment.
 * `resolvePlaybackSegments` matches no clip for such a row, so it removed nothing from the
 * film, the preview or the export; all it did was strike the word through. Now that both
 * lanes read the same removed set, leaving those rows behind would keep striking words
 * through for a cut that never existed.
 *
 * The test is exact and needs no clip lookup: an audio asset is never a clip's `assetId`
 * (audio is filtered out of the lists that make clips), so a trim naming one can only have
 * come from that build. An un-anchored pre-v7 trim names a VIDEO asset and is untouched;
 * so is a trim whose clip was deleted, which in-session undo can still bring back.
 *
 * No `schemaVersion` bump: nothing about the format changed, and no output moves — these
 * rows were already inert. What changes is that words the user "deleted" on that build
 * come back as kept, which is the correction, and belongs in the release note.
 *
 * Runs on RAW, untrusted input like the rest of the chain, so every read is guarded.
 */
function dropAudioAnchoredTrims(raw: unknown): unknown {
	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
	const doc = raw as Record<string, unknown>;
	const assets = Array.isArray(doc.assets) ? doc.assets : null;
	if (!assets) return raw;
	const audioAssetIds = new Set<string>();
	for (const asset of assets) {
		if (!asset || typeof asset !== "object" || Array.isArray(asset)) continue;
		const entry = asset as Record<string, unknown>;
		if (entry.kind === "audio" && typeof entry.id === "string") audioAssetIds.add(entry.id);
	}
	if (audioAssetIds.size === 0) return raw;

	const timeline =
		doc.timeline && typeof doc.timeline === "object" && !Array.isArray(doc.timeline)
			? (doc.timeline as Record<string, unknown>)
			: null;
	const trims = timeline && Array.isArray(timeline.trimRanges) ? timeline.trimRanges : null;
	if (!trims) return raw;

	const kept = trims.filter((entry) => {
		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return true;
		const trim = entry as Record<string, unknown>;
		return !(typeof trim.assetId === "string" && audioAssetIds.has(trim.assetId));
	});
	if (kept.length === trims.length) return raw;
	return { ...doc, timeline: { ...timeline, trimRanges: kept } };
}

/**
 * Raise to its start the end of every transcript segment or word stored BEFORE its start.
 *
 * The transcription core before a9fdd97ff (transformers.js, removed 2026-07-05) clamped a
 * timestamp's end to the audio length but not its start, so a Whisper hallucination past the
 * end of the audio ("very good" at 13.5 s in 6.76 s of sound) was written as [13.5, 6.76].
 * The schema rejects that, and a single such word made the whole project unreadable: it
 * vanished from the project list.
 *
 * Raising the end loses nothing: the text, any edit made to it, and every id a segment or a
 * caption refers to all survive. The word becomes a zero-length point at its start, which in
 * the known case lies past the media, so it plays and shows nowhere.
 *
 * No `schemaVersion` bump, like `dropAudioAnchoredTrims`: the document comes back untouched
 * when there is nothing to repair. Runs on RAW, untrusted input, so every read is guarded.
 */
function raiseInvertedTranscriptEnds(raw: unknown): unknown {
	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
	const doc = raw as Record<string, unknown>;
	let repaired = false;
	const repairSpans = (spans: unknown): unknown => {
		if (!Array.isArray(spans)) return spans;
		return spans.map((entry) => {
			if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
			const span = entry as Record<string, unknown>;
			if (typeof span.startSec !== "number" || typeof span.endSec !== "number") return entry;
			if (span.endSec >= span.startSec) return entry;
			repaired = true;
			return { ...span, endSec: span.startSec };
		});
	};
	const repairTranscript = (value: unknown): unknown => {
		if (!value || typeof value !== "object" || Array.isArray(value)) return value;
		const transcript = value as Record<string, unknown>;
		return {
			...transcript,
			segments: repairSpans(transcript.segments),
			words: repairSpans(transcript.words),
		};
	};
	const transcript = repairTranscript(doc.transcript);
	const transcripts = Array.isArray(doc.transcripts)
		? doc.transcripts.map(repairTranscript)
		: doc.transcripts;
	return repaired ? { ...doc, transcript, transcripts } : raw;
}

/**
 * Carry a zoom's click impact over to the cursor setting it became.
 *
 * Builds up to v1.13.0 stored `clickImpact` on each zoom range, and only a 3D camera used it.
 * It is now a cursor setting (`legacyEditor.cursorClickImpact`) that acts under every camera,
 * and the zoom range schema no longer has the key, so the parse would drop it silently. A
 * document that turned it on for any zoom keeps it on, now for the whole project; one that
 * never did, or already stores the cursor setting, comes back untouched.
 *
 * No `schemaVersion` bump, like `dropAudioAnchoredTrims`. Runs on RAW, untrusted input, so
 * every read is guarded.
 */
function liftZoomClickImpact(raw: unknown): unknown {
	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
	const doc = raw as Record<string, unknown>;
	const zooms = Array.isArray(doc.zoomRanges) ? doc.zoomRanges : [];
	const on = zooms.some(
		(zoom) =>
			zoom && typeof zoom === "object" && (zoom as Record<string, unknown>).clickImpact === true,
	);
	if (!on) return raw;
	const legacy =
		doc.legacyEditor && typeof doc.legacyEditor === "object" && !Array.isArray(doc.legacyEditor)
			? (doc.legacyEditor as Record<string, unknown>)
			: null;
	if (typeof legacy?.cursorClickImpact === "boolean") return raw;
	return { ...doc, legacyEditor: { ...legacy, cursorClickImpact: true } };
}

/**
 * Read a zoom stored with the `follow-cursor` camera as the `orbit` camera under auto focus.
 *
 * `follow-cursor` was the orbit before it had a manual mode: it followed the cursor whatever the
 * zoom's focus mode said, and most such zooms carry "manual", the default. The camera now reads
 * the focus mode like every other zoom, so the auto focus is written down along with the new
 * name, and the zoom keeps following the cursor as it did.
 *
 * No `schemaVersion` bump, as for `iso` → `left`: the retired value is the marker, and nothing
 * writes it any more, so a second run finds nothing. A document without such a zoom comes back
 * untouched. Runs on RAW, untrusted input, so every read is guarded.
 */
function readFollowCursorAsAutoOrbit(raw: unknown): unknown {
	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
	const doc = raw as Record<string, unknown>;
	if (!Array.isArray(doc.zoomRanges)) return raw;
	let renamed = false;
	const zoomRanges = doc.zoomRanges.map((entry) => {
		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
		const zoom = entry as Record<string, unknown>;
		if (zoom.rotationPreset !== "follow-cursor") return entry;
		renamed = true;
		return { ...zoom, rotationPreset: "orbit", focusMode: "auto" };
	});
	return renamed ? { ...doc, zoomRanges } : raw;
}

export function migrateRawDocumentToCurrent(raw: unknown): unknown {
	return upgradeV8DocumentToV9(
		readFollowCursorAsAutoOrbit(
			raiseInvertedTranscriptEnds(
				dropAudioAnchoredTrims(
					liftZoomClickImpact(
						upgradeV7DocumentToV8(
							upgradeV6DocumentToV7(
								upgradeV5DocumentToV6(upgradeV4DocumentToV5(upgradeV3DocumentToV4(raw))),
							),
						),
					),
				),
			),
		),
	);
}

// PURE v9 validation. Callers that read a document from disk (or any other
// source that might carry an older `schemaVersion`) MUST run
// `migrateRawDocumentToCurrent` on the raw value first. The previous
// implementation wrapped this schema in a `z.preprocess` that re-ran the whole
// v3→…→v8 chain on EVERY parse, including in-memory parses of documents that
// were already current. Hoisting it to load time makes the in-memory parse a
// single `z.literal(8)` + shape check.
export const documentSchema = documentSchemaShape;

/**
 * Whether a parsed `.openscreen` file is an AxcutDocument — what the editor saves, at any
 * `schemaVersion` — rather than a legacy v2 `{ version, media, editor }` project, which must go
 * through `migrateProjectDataToAxcutDocument` instead (it reads `.media` / `.editor` and would
 * yield an empty document from a current one).
 */
export function isAxcutDocumentFile(raw: unknown): raw is Record<string, unknown> {
	return typeof raw === "object" && raw !== null && "schemaVersion" in raw && "timeline" in raw;
}

/** A document read from a file, at any supported `schemaVersion`: upgraded, then validated. */
export function parseDocumentFile(raw: unknown): AxcutDocument {
	return documentSchema.parse(migrateRawDocumentToCurrent(raw));
}

export const createProjectInputSchema = z.object({
	title: z.string().trim().min(1).default("Untitled Project"),
});

// Every code whisper.cpp's multilingual model can resolve, plus "auto" for
// detection. Codes and order mirror whisper.cpp's own `g_lang` table
// (`src/whisper.cpp`, verified against the tag `nix/whisper-stt.nix` pins —
// v1.9.1) — `wparams.language` in
// electron/native/whisper-stt/src/main.cpp forwards the code verbatim, so a
// value outside this list fails to resolve a language id there. "auto" is
// always index 0 — code that needs "every real language, no sentinel" relies
// on that (see `WhisperLanguageCode` below) rather than filtering it out.
// Consumed by the "Regenerate as" picker in `MediaStage.tsx`. A second,
// unreachable copy lived in the v3 left panel's transcript modal until that
// whole surface was deleted — see decisions.md.
export const TRANSCRIPT_LANGUAGE_CODES = [
	"auto",
	"en",
	"zh",
	"de",
	"es",
	"ru",
	"ko",
	"fr",
	"ja",
	"pt",
	"tr",
	"pl",
	"ca",
	"nl",
	"ar",
	"sv",
	"it",
	"id",
	"hi",
	"fi",
	"vi",
	"he",
	"uk",
	"el",
	"ms",
	"cs",
	"ro",
	"da",
	"hu",
	"ta",
	"no",
	"th",
	"ur",
	"hr",
	"bg",
	"lt",
	"la",
	"mi",
	"ml",
	"cy",
	"sk",
	"te",
	"fa",
	"lv",
	"bn",
	"sr",
	"az",
	"sl",
	"kn",
	"et",
	"mk",
	"br",
	"eu",
	"is",
	"hy",
	"ne",
	"mn",
	"bs",
	"kk",
	"sq",
	"sw",
	"gl",
	"mr",
	"pa",
	"si",
	"km",
	"sn",
	"yo",
	"so",
	"af",
	"oc",
	"ka",
	"be",
	"tg",
	"sd",
	"gu",
	"am",
	"yi",
	"lo",
	"uz",
	"fo",
	"ht",
	"ps",
	"tk",
	"nn",
	"mt",
	"sa",
	"lb",
	"my",
	"bo",
	"tl",
	"mg",
	"as",
	"tt",
	"haw",
	"ln",
	"ha",
	"ba",
	"jw",
	"su",
	"yue",
] as const;

export const transcriptLanguageSchema = z.enum(TRANSCRIPT_LANGUAGE_CODES);

export type AxcutWord = z.infer<typeof wordSchema>;
export type AxcutTranscriptSegment = z.infer<typeof transcriptSegmentSchema>;
export type AxcutTranscript = z.infer<typeof transcriptSchema>;
export type AxcutAsset = z.infer<typeof assetSchema>;
export type AxcutAssetTranscriptionFailure = z.infer<typeof assetTranscriptionFailureSchema>;
export type AxcutClip = z.infer<typeof clipSchema>;
export type AxcutClipCropRegion = z.infer<typeof clipCropRegionSchema>;
export type AxcutGap = z.infer<typeof gapSchema>;
export type AxcutTrimRange = z.infer<typeof trimRangeSchema>;
export type AxcutTimeline = z.infer<typeof timelineSchema>;
export type AxcutTimelineOperation = z.infer<typeof timelineOperationSchema>;
export type AxcutAnnotationRegion = z.infer<typeof annotationRegionSchema>;
export type AxcutZoomRegion = z.infer<typeof zoomRegionSchema>;
export type AxcutCameraTrack = z.infer<typeof cameraTrackSchema>;
export type AxcutAudioTrack = z.infer<typeof audioTrackSchema>;
export type AxcutShaderEffect = z.infer<typeof shaderEffectSchema>;
export type AxcutShaderEffectParam = z.infer<typeof shaderEffectParamSchema>;
export type AxcutShaderEffectRange = z.infer<typeof shaderEffectRangeSchema>;
export type AxcutShaderEffectValue = z.infer<typeof shaderEffectValueSchema>;
export type AxcutLegacyEditor = z.infer<typeof legacyEditorSchema>;
export type AxcutDocument = z.infer<typeof documentSchema>;
export type AxcutDocumentInput = z.input<typeof documentSchema>;
export type CreateProjectInput = z.infer<typeof createProjectInputSchema>;
export type TranscriptLanguageCode = z.infer<typeof transcriptLanguageSchema>;
/** A real whisper.cpp language code — `TranscriptLanguageCode` minus the "auto" detection sentinel. */
export type WhisperLanguageCode = Exclude<TranscriptLanguageCode, "auto">;

export function createEmptyDocument(
	input: CreateProjectInput & { projectId: string; createdAt?: string },
): AxcutDocument {
	const createdAt = input.createdAt ?? new Date().toISOString();
	return documentSchema.parse({
		schemaVersion: axcutSchemaVersion,
		project: {
			id: input.projectId,
			title: input.title,
			createdAt,
			updatedAt: createdAt,
		},
		assets: [],
		transcript: null,
		transcripts: [],
		timeline: {
			clips: [],
			gaps: [],
			trimRanges: [],
			muteRanges: [],
			speedRanges: [],
			captionRanges: [],
		},
		annotations: [],
		zoomRanges: [],
		audioTracks: [],
		legacyEditor: null,
	});
}

export function ensureDocument(value: unknown): AxcutDocument {
	return documentSchema.parse(value);
}

/**
 * The level and ramps a track starts with. A music bed sits UNDER the voice, at −18 dB,
 * and eases in and out over a second instead of cutting in; a voiceover is voice, levelled
 * by the export like the recording itself, so it starts flat.
 *
 * Applied when a track is created, and by the inspector's reset. Deliberately NOT the
 * schema's parse defaults above: a track saved before these existed keeps the level its
 * author set.
 */
export function audioTrackDefaults(
	kind: AxcutAudioTrack["kind"],
): Pick<AxcutAudioTrack, "gainDb" | "fadeInMs" | "fadeOutMs"> {
	return kind === "music"
		? { gainDb: -18, fadeInMs: 1000, fadeOutMs: 1000 }
		: { gainDb: 0, fadeInMs: 0, fadeOutMs: 0 };
}

/**
 * Build a timeline audio track for an imported or recorded audio asset
 * (issue #350). The head is placed at `timelineStartSec` (RAW/document timeline
 * seconds — the same clock the ruler, playhead and clip `timelineStartSec` use,
 * NOT the trim-compressed output programme; the export projects it with
 * `projectRawTimelineSecToPlayback`) and the track spans the whole source file
 * unless the caller asks for a shorter `spanSec`. Starts at its kind's
 * `audioTrackDefaults`, then parsed through the schema so every other default
 * (loop, mute) is applied in one place.
 *
 * The result is UNANCHORED — `clipId` is absent. Callers place it through
 * `anchorAudioTrackFragments`, which ventilates it across the clips it covers.
 */
export function createAudioTrack(input: {
	assetId: string;
	durationSec: number;
	kind?: "voiceover" | "music";
	/** Raw ruler head. The span runs from here for `durationSec`, or for
	 *  `spanSec` when the caller wants a shorter placement than the file. */
	timelineStartSec?: number;
	spanSec?: number;
	label?: string;
}): AxcutAudioTrack {
	const startMs = Math.round(Math.max(0, input.timelineStartSec ?? 0) * 1000);
	// A track with no measurable source still needs a visible span, or the pill
	// is zero-width and cannot be grabbed to fix.
	const spanMs = Math.max(1, Math.round((input.spanSec ?? input.durationSec) * 1000));
	const kind = input.kind ?? "music";
	return audioTrackSchema.parse({
		id: createId("audio"),
		assetId: input.assetId,
		kind,
		...audioTrackDefaults(kind),
		durationSec: input.durationSec,
		startMs,
		endMs: startMs + spanMs,
		label: input.label ?? "",
	});
}