Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
import { assertAudioLevelAutomation } from "./audio-level-automation.js";
import type { AudioLevelAutomation, AudioSampleSpan } from "./audio-level-automation.js";
import { canonicalStringify, isResourceId } from "@hypit/hypit/protocol";
import type { BlobRef, CanonicalValue } from "@hypit/hypit/protocol";
import {
assertVisualStyleV1,
VISUAL_IR_V1,
} from "./visual.js";
import { assertTimelineIdentity, timelineFrameCount, timelineSampleFrames } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import { assertCompositableSurfaceRef, assertFontArtifactRef } from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
export type FrameSpan = {
readonly startFrame: number;
readonly endFrameExclusive: number;
};
/** One inline style declaration inside a Present-owned element tree. */
export type VisualStyleDeclaration = {
readonly name: string;
readonly value: string | number;
};
export type VisualAttribute = {
readonly name: string;
readonly value: string;
};
export type VisualEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
/**
* A frame-exact, code-free animation owned by one element. Keyframe offsets
* are relative to the containing Present and therefore remain deterministic
* under local and hosted rendering.
*/
export type VisualKeyframe = {
readonly atFrame: number;
readonly easing?: VisualEasing;
readonly style: readonly VisualStyleDeclaration[];
};
export type VisualAnimation = {
readonly keyframes: readonly VisualKeyframe[];
};
export type VisualElementBase = {
readonly id: string;
readonly parent?: string;
readonly order: number;
readonly style: readonly VisualStyleDeclaration[];
readonly attributes?: readonly VisualAttribute[];
readonly animation?: VisualAnimation;
};
export type VisualBoxElement = VisualElementBase & {
readonly kind: "box";
};
/** A renderer-interpreted local program. Its format and payload belong to its rendering package. */
export type VisualProgramElement = VisualElementBase & {
readonly kind: "program";
readonly program: {
readonly format: string;
readonly payload: { readonly [key: string]: CanonicalValue };
readonly artifacts: readonly BlobRef[];
};
};
/** A strictly local two-input mask. Both roots are direct owned children in the same Present. */
export type VisualMaskElement = VisualElementBase & {
readonly kind: "mask";
readonly mode: "alpha" | "luminance";
readonly maskElement: string;
readonly contentElement: string;
};
export type VisualTextElement = VisualElementBase & {
readonly kind: "text";
readonly text: string;
/** Exact ordered fallback faces. Terminal Visual IR never depends on environment fonts. */
readonly fonts: readonly FontArtifactRef[];
/**
* Ordered glyph Paint, in the same vocabulary Text Flow uses.
*
* Style alone can only say `-webkit-text-stroke`, which centres an outline on the glyph edge and
* therefore spends half its width inside the letter. An outline that is asked to sit outside the
* letter cannot be expressed that way at all. Declaring the Paint instead lets the renderer build
* the placement that was asked for, and `stroke` before `fill` orders them.
*/
readonly paints?: readonly VisualTextPaintLayer[];
};
export type VisualTextDirection = "auto" | "ltr" | "rtl";
export type VisualTextWritingMode = "horizontal-tb" | "vertical-rl" | "vertical-lr";
export type VisualTextTypography = {
/** Exact ordered faces. Author-package prototype families must resolve before this boundary. */
readonly fonts: readonly FontArtifactRef[];
readonly sizePx: number;
readonly weight: number;
readonly style: "normal" | "italic" | "oblique";
readonly axes: readonly { readonly tag: string; readonly value: number }[];
readonly features: readonly { readonly tag: string; readonly enabled: boolean }[];
readonly synthesis: "none" | "weight" | "style" | "weight-style";
readonly kerning: "auto" | "normal" | "none";
readonly trackingPx: number;
readonly wordSpacingPx: number;
readonly lineHeight: number;
readonly language?: string;
readonly direction: VisualTextDirection;
readonly writingMode: VisualTextWritingMode;
readonly baselineShiftPx: number;
readonly tabSize: number;
readonly indentationPx: number;
readonly paragraphBeforePx: number;
readonly paragraphAfterPx: number;
readonly transform: "none" | "uppercase" | "lowercase" | "capitalize";
readonly variantCaps: "normal" | "small-caps" | "all-small-caps";
readonly verticalAlign: "baseline" | "super" | "sub";
readonly decorations: readonly VisualTextDecoration[];
readonly cjk: {
readonly textSpacing: "normal" | "none";
readonly punctuationTrim: "none" | "start" | "end" | "adjacent" | "all";
};
};
/** Explicit run override. Omitted properties inherit; authored text never changes. */
export type VisualTextRunStyle = {
readonly typography?: Partial<VisualTextTypography>;
readonly paints?: readonly VisualTextPaintLayer[];
};
export type VisualTextInline =
| {
readonly kind: "text";
readonly id: string;
readonly text: string;
readonly style?: VisualTextRunStyle;
readonly language?: string;
readonly direction?: VisualTextDirection;
}
| { readonly kind: "break"; readonly id: string };
export type VisualTextDocument = {
readonly paragraphs: readonly {
readonly id: string;
readonly inlines: readonly VisualTextInline[];
readonly style?: VisualTextRunStyle;
}[];
};
export type VisualColorPaint =
| { readonly kind: "solid"; readonly color: string }
| {
readonly kind: "linear-gradient";
readonly angleDeg: number;
readonly stops: readonly { readonly offset: number; readonly color: string; readonly opacity: number }[];
}
| {
readonly kind: "radial-gradient";
readonly center: { readonly x: number; readonly y: number };
readonly stops: readonly { readonly offset: number; readonly color: string; readonly opacity: number }[];
};
export type VisualTextDecoration = {
readonly line: "underline" | "overline" | "line-through";
readonly paint: VisualColorPaint;
readonly style: "solid" | "double" | "dotted" | "dashed" | "wavy";
readonly thicknessPx?: number;
readonly offsetPx?: number;
readonly skipInk: boolean;
};
export type VisualTextBoxDecoration = {
readonly fill?: VisualColorPaint;
readonly border?: {
readonly paint: VisualColorPaint;
readonly widthsPx: { readonly top: number; readonly right: number; readonly bottom: number; readonly left: number };
readonly style: "solid" | "dashed" | "dotted";
};
readonly paddingPx: { readonly top: number; readonly right: number; readonly bottom: number; readonly left: number };
readonly radiiPx: { readonly topLeft: number; readonly topRight: number; readonly bottomRight: number; readonly bottomLeft: number };
readonly shadows: readonly {
readonly paint: VisualColorPaint;
readonly offsetX: number;
readonly offsetY: number;
readonly blurPx: number;
readonly spreadPx: number;
}[];
readonly tail?: {
readonly side: "top" | "right" | "bottom" | "left";
readonly offset: number;
readonly widthPx: number;
readonly heightPx: number;
readonly paint: VisualColorPaint;
};
};
export type VisualTextPaintTarget = "frame" | "content" | "paragraph" | "line" | "run" | "word" | "grapheme";
/** Ordered renderer-neutral text Paint. Repetition and array order are semantic. */
export type VisualTextPaintLayer =
| { readonly kind: "fill"; readonly paint: VisualColorPaint }
| {
readonly kind: "stroke";
readonly paint: VisualColorPaint;
readonly widthPx: number;
readonly placement: "inside" | "center" | "outside";
}
| {
readonly kind: "shadow";
readonly paint: VisualColorPaint;
readonly offsetX: number;
readonly offsetY: number;
readonly blurPx: number;
readonly spreadPx: number;
}
| { readonly kind: "glow"; readonly paint: VisualColorPaint; readonly blurPx: number; readonly spreadPx: number }
| {
readonly kind: "box";
readonly target: VisualTextPaintTarget;
readonly continuity: "isolated" | "joined";
readonly decoration: VisualTextBoxDecoration;
};
export type VisualTextFlow = {
readonly form:
| {
readonly kind: "point";
readonly anchorInline: "start" | "center" | "end";
readonly anchorBlock: "start" | "center" | "end";
}
| { readonly kind: "area" };
readonly inlineSize: "hug" | "fixed";
readonly blockSize: "hug" | "fixed";
readonly paddingPx: { readonly inlineStart: number; readonly inlineEnd: number; readonly blockStart: number; readonly blockEnd: number };
readonly inlineAlign: "start" | "center" | "end" | "justify";
readonly blockAlign: "start" | "center" | "end";
readonly wrap: "none" | "word" | "grapheme";
readonly overflow: "visible" | "clip" | "ellipsis" | "shrink";
readonly maxLines?: number;
readonly minimumScale?: number;
readonly clipToFrame: boolean;
readonly columns: number;
readonly columnGapPx: number;
readonly metricEdge: "line-box" | "cap-height" | "ink";
};
export type VisualTextSequenceAnimation = {
readonly id: string;
readonly unit: "paragraph" | "line" | "run" | "word" | "grapheme";
readonly range: { readonly start: number; readonly endExclusive: number };
readonly order: "forward" | "reverse" | "random";
readonly startFrame: number;
readonly unitDurationFrames: number;
readonly staggerFrames: number;
readonly cycles: number;
readonly seed?: number;
readonly keyframes: readonly {
readonly atProgress: number;
readonly easing?: VisualEasing;
readonly style: readonly VisualStyleDeclaration[];
}[];
};
/** Exact terminal text flow. It contains no author Style/Recipe reference or renderer callback. */
export type VisualTextFlowElement = VisualElementBase & {
readonly kind: "text-flow";
readonly document: VisualTextDocument;
readonly typography: VisualTextTypography;
readonly paints: readonly VisualTextPaintLayer[];
readonly flow: VisualTextFlow;
readonly sequences: readonly VisualTextSequenceAnimation[];
};
export type VisualVectorPathCommand =
| { readonly kind: "move" | "line"; readonly x: number; readonly y: number }
| { readonly kind: "quadratic"; readonly controlX: number; readonly controlY: number; readonly x: number; readonly y: number }
| { readonly kind: "cubic"; readonly control1X: number; readonly control1Y: number; readonly control2X: number; readonly control2Y: number; readonly x: number; readonly y: number }
| { readonly kind: "close" };
export type VisualPathTextElement = VisualElementBase & {
readonly kind: "path-text";
readonly document: VisualTextDocument;
readonly typography: VisualTextTypography;
readonly paints: readonly VisualTextPaintLayer[];
readonly path: readonly VisualVectorPathCommand[];
readonly side: "left" | "right";
readonly orientation: "follow" | "upright";
readonly startMarginPx: number;
readonly endMarginPx: number;
readonly align: "start" | "center" | "end";
readonly reverse: boolean;
readonly overflow: "visible" | "clip";
readonly sequences: readonly VisualTextSequenceAnimation[];
readonly marginAnimation?: {
readonly keyframes: readonly {
readonly atFrame: number;
readonly startMarginPx: number;
readonly easing?: VisualEasing;
}[];
};
};
export type VisualSourceTimeRational = {
readonly numerator: number;
readonly denominator: number;
};
/**
* One exact piece of a timed visual's source-time function. Target frames are
* relative to the containing Present. A gap means the material is invisible.
*/
export type VisualSourceTimePiece = {
readonly target: FrameSpan;
/** Absolute source-frame position at target.startFrame. */
readonly sourceAtStart: VisualSourceTimeRational;
/** Source frames advanced per Program frame; zero is an exact held frame. */
readonly rate: VisualSourceTimeRational;
/** Half-open source interval used for periodic evaluation. */
readonly wrap?: FrameSpan;
};
export type VisualSourceTimeMap = {
readonly sourceFrameRate: VisualSourceTimeRational;
readonly sourceFrameCount: number;
readonly pieces: readonly VisualSourceTimePiece[];
};
export type VisualMediaElement =
| (VisualElementBase & {
readonly kind: "image";
readonly artifact: BlobRef;
})
| (VisualElementBase & {
readonly kind: "video";
readonly artifact: BlobRef;
/** Exact partial frame-domain function for this timed source. */
readonly sourceTime: VisualSourceTimeMap;
readonly muted?: boolean;
});
/** A package-materialized visual surface with content-bound compositing metadata, not an untyped media guess. */
export type VisualSurfaceElement = VisualElementBase & {
readonly kind: "surface";
readonly surface: CompositableSurfaceRef;
/** Required exactly when surface.timing is frames; absent for a still Surface. */
readonly sourceTime?: VisualSourceTimeMap;
};
/**
* Structural elements and explicit renderer programs compose in one owned tree.
*
* A Present holds exactly one root; everything else names a `parent`, which can be a box,
* mask or program. **Position is measured from that parent, not from the Canvas.** A component that computes
* its layout in Canvas pixels and then nests its elements has to subtract the parent's own origin,
* or every child lands offset by it — which draws without complaint and is wrong by exactly the
* distance the parent sits from the corner.
*/
export type VisualElement = VisualBoxElement | VisualProgramElement | VisualMaskElement | VisualTextElement | VisualTextFlowElement | VisualPathTextElement | VisualMediaElement | VisualSurfaceElement;
export type VisualPresent = {
readonly id: string;
/** Stable order among Presents emitted by this owning Track. */
readonly order: number;
/** Author-owned absolute picture stacking position across Tracks. */
readonly z: number;
/** Optional domain entity implemented by this renderer Present. */
readonly subjectId?: string;
readonly span: FrameSpan;
/** Optional visible subranges in program frames; span remains the animation and sampling origin. */
readonly visibility?: readonly FrameSpan[];
readonly elements: readonly VisualElement[];
};
export type VisualTrack = {
readonly kind: "visual";
/** Timeline identity this terminal placement was rendered against. */
readonly timelineId: string;
/** The one terminal visual language shared by official video components. */
readonly visualIr: typeof VISUAL_IR_V1;
readonly id: string;
/** Author-owned contributions that Composition may interleave by absolute z. */
readonly presents: readonly VisualPresent[];
};
export type AudioSourceTimeRational = {
readonly numerator: number;
readonly denominator: number;
};
export type AudioSourceTimePiece = {
/** Clip-local target samples. Uncovered samples are silent. */
readonly target: AudioSampleSpan;
readonly sourceAtStart: AudioSourceTimeRational;
/** Positive source samples advanced per target sample. */
readonly rate: AudioSourceTimeRational;
readonly wrap?: AudioSampleSpan;
};
export type AudioSourceTimeMap = {
readonly sourceSampleFrames: number;
readonly pieces: readonly AudioSourceTimePiece[];
};
export type AudioClip = AudioLevelAutomation & {
readonly id: string;
/** Optional domain entity implemented by this renderer Clip. */
readonly subjectId?: string;
/** Bytes only. Exact duration belongs to source.sampleFrames, not duplicated floating metadata. */
readonly artifact: BlobRef;
/** Exact audible placement in the canonical 48 kHz Timeline sample domain. */
readonly target: {
readonly startSample: number;
readonly endSampleExclusive: number;
};
/** Partial Clip-local target-to-source relation for one canonical 48 kHz stereo WAV Artifact. */
readonly sourceTime: AudioSourceTimeMap;
readonly gain: number;
readonly fadeInSamples: number;
readonly fadeOutSamples: number;
};
export type AudioTrack = {
readonly kind: "audio";
/** Timeline identity this terminal placement was rendered against. */
readonly timelineId: string;
readonly id: string;
readonly clips: readonly AudioClip[];
};
export type Track = VisualTrack | AudioTrack;
export type Composition = {
readonly id: string;
readonly canvas: {
readonly width: number;
readonly height: number;
/** Structural clear color beneath every VisualTrack. */
readonly clearColor: string;
};
readonly tracks: readonly Track[];
};
/** The only local style properties accepted in element keyframes. */
export const animatableLocalStyles = [
"backdrop-filter",
"clip-path",
"filter",
"opacity",
"transform",
] as const;
const ANIMATABLE_LOCAL_STYLES = new Set<string>(animatableLocalStyles);
const ANIMATABLE_TEXT_UNIT_STYLES = new Set([
"-webkit-text-fill-color",
"-webkit-text-stroke-color",
"background-color",
"color",
"filter",
"opacity",
"transform",
]);
function assertNonEmpty(value: string, label: string): void {
if (!value) throw new Error(`${label} must not be empty.`);
}
function assertFrameSpan(span: FrameSpan, totalFrames: number, label: string): void {
if (
!Number.isSafeInteger(span.startFrame)
|| !Number.isSafeInteger(span.endFrameExclusive)
|| span.startFrame < 0
|| span.endFrameExclusive <= span.startFrame
|| span.endFrameExclusive > totalFrames
) {
throw new Error(`${label} is outside Timeline.`);
}
}
function assertMediaArtifact(artifact: BlobRef, label: string): void {
if (
artifact.kind !== "blob"
|| !isResourceId(artifact.resource)
|| !Number.isSafeInteger(artifact.size)
|| artifact.size < 0
|| !artifact.mediaType
) {
throw new Error(`${label} is invalid.`);
}
}
function assertRational(value: VisualSourceTimeRational, label: string, sign: "positive" | "non-negative" | "signed"): void {
if (!Number.isSafeInteger(value.numerator)
|| (sign === "positive" && value.numerator <= 0)
|| (sign === "non-negative" && value.numerator < 0)
|| !Number.isSafeInteger(value.denominator) || value.denominator <= 0) {
throw new Error(`${label} is not a safe ${sign} rational.`);
}
}
function compareRationalToInteger(value: VisualSourceTimeRational, integer: number): number {
const difference = BigInt(value.numerator) - BigInt(integer) * BigInt(value.denominator);
return difference < 0n ? -1 : difference > 0n ? 1 : 0;
}
function sourceAt(piece: VisualSourceTimePiece, targetOffset: number): VisualSourceTimeRational {
const denominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
const numerator = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ BigInt(targetOffset) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
if (numerator > BigInt(Number.MAX_SAFE_INTEGER) || numerator < BigInt(Number.MIN_SAFE_INTEGER)
|| denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
throw new Error("Visual source-time arithmetic exceeds the safe wire domain.");
}
return { numerator: Number(numerator), denominator: Number(denominator) };
}
function assertSourceTime(value: VisualSourceTimeMap, durationFrames: number, label: string): void {
assertRational(value.sourceFrameRate, `${label}.sourceFrameRate`, "positive");
if (!Number.isSafeInteger(value.sourceFrameCount) || value.sourceFrameCount <= 0 || value.pieces.length === 0) {
throw new Error(`${label} source frame domain is invalid.`);
}
let previousEnd = 0;
for (const [index, piece] of value.pieces.entries()) {
const item = `${label}.pieces.${index}`;
if (!Number.isSafeInteger(piece.target.startFrame) || !Number.isSafeInteger(piece.target.endFrameExclusive)
|| piece.target.startFrame < previousEnd || piece.target.endFrameExclusive <= piece.target.startFrame
|| piece.target.endFrameExclusive > durationFrames) throw new Error(`${item} target interval is invalid.`);
assertRational(piece.sourceAtStart, `${item}.sourceAtStart`, "non-negative");
assertRational(piece.rate, `${item}.rate`, "signed");
if (piece.wrap !== undefined) {
if (!Number.isSafeInteger(piece.wrap.startFrame) || !Number.isSafeInteger(piece.wrap.endFrameExclusive)
|| piece.wrap.startFrame < 0 || piece.wrap.endFrameExclusive <= piece.wrap.startFrame
|| piece.wrap.endFrameExclusive > value.sourceFrameCount
|| compareRationalToInteger(piece.sourceAtStart, piece.wrap.startFrame) < 0
|| compareRationalToInteger(piece.sourceAtStart, piece.wrap.endFrameExclusive) >= 0) {
throw new Error(`${item} wrap interval or phase is invalid.`);
}
} else {
const last = sourceAt(piece, piece.target.endFrameExclusive - piece.target.startFrame - 1);
if (compareRationalToInteger(piece.sourceAtStart, 0) < 0
|| compareRationalToInteger(piece.sourceAtStart, value.sourceFrameCount) >= 0
|| compareRationalToInteger(last, 0) < 0
|| compareRationalToInteger(last, value.sourceFrameCount) >= 0) {
throw new Error(`${item} samples outside its source frame domain.`);
}
}
previousEnd = piece.target.endFrameExclusive;
}
}
function assertAudioArtifact(artifact: BlobRef, label: string): void {
if (
artifact.kind !== "blob"
|| !isResourceId(artifact.resource)
|| !Number.isSafeInteger(artifact.size)
|| artifact.size < 0
|| artifact.mediaType !== "audio/wav"
) {
throw new Error(`${label} must be a canonical WAV BlobRef.`);
}
}
function assertStyle(style: readonly VisualStyleDeclaration[], label: string): void {
const names = new Set<string>();
for (const declaration of style) {
if (names.has(declaration.name)) {
throw new Error(`${label} contains duplicate style ${declaration.name}.`);
}
names.add(declaration.name);
assertVisualStyleV1(declaration.name, declaration.value, label);
}
}
function assertAttributes(attributes: readonly VisualAttribute[] | undefined, label: string): void {
const names = new Set<string>();
for (const attribute of attributes ?? []) {
if (!/^(?:data-[a-z0-9-]+|aria-[a-z0-9-]+|role|title|lang|dir)$/u.test(attribute.name)) {
throw new Error(`${label} contains unsafe attribute ${attribute.name}.`);
}
if (attribute.name === "lang" && !/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/u.test(attribute.value)) {
throw new Error(`${label} contains invalid lang ${attribute.value}.`);
}
if (attribute.name === "dir" && !["ltr", "rtl", "auto"].includes(attribute.value)) {
throw new Error(`${label} contains invalid dir ${attribute.value}.`);
}
if (names.has(attribute.name)) {
throw new Error(`${label} contains duplicate attribute ${attribute.name}.`);
}
names.add(attribute.name);
}
}
function assertExactFonts(fonts: readonly FontArtifactRef[], label: string): void {
if (fonts.length === 0) throw new Error(`${label} has an empty font stack.`);
const faces = new Set<string>();
for (const [index, font] of fonts.entries()) {
assertFontArtifactRef(font, `${label}.${index}`);
const face = canonicalStringify(font);
if (faces.has(face)) throw new Error(`${label} has a duplicate font face.`);
faces.add(face);
}
}
function finite(value: number, label: string): void {
if (!Number.isFinite(value)) throw new Error(`${label} must be finite.`);
}
function nonNegative(value: number, label: string): void {
finite(value, label);
if (value < 0) throw new Error(`${label} must not be negative.`);
}
function assertColor(value: string, label: string): void {
assertNonEmpty(value, label);
if (value.length > 256
|| /[;{}<>"'\\]|!important|[\u0000-\u001f\u007f]/iu.test(value)
|| /(?:url|var|env|attr|image-set)\s*\(/iu.test(value)) {
throw new Error(`${label} contains an unsafe or environment-dependent color.`);
}
}
function assertColorPaint(paint: VisualColorPaint, label: string): void {
if (paint.kind === "solid") {
assertColor(paint.color, `${label}.color`);
return;
}
if (paint.kind !== "linear-gradient" && paint.kind !== "radial-gradient") {
throw new Error(`${label} has an unsupported Paint kind.`);
}
if (paint.kind === "linear-gradient") finite(paint.angleDeg, `${label}.angleDeg`);
else {
finite(paint.center.x, `${label}.center.x`);
finite(paint.center.y, `${label}.center.y`);
if (paint.center.x < 0 || paint.center.x > 1 || paint.center.y < 0 || paint.center.y > 1) {
throw new Error(`${label}.center must be normalized.`);
}
}
if (paint.stops.length < 2) throw new Error(`${label} requires at least two gradient stops.`);
let previous = -1;
for (const [index, stop] of paint.stops.entries()) {
finite(stop.offset, `${label}.stops.${index}.offset`);
finite(stop.opacity, `${label}.stops.${index}.opacity`);
assertColor(stop.color, `${label}.stops.${index}.color`);
if (stop.offset < 0 || stop.offset > 1 || stop.offset < previous || stop.opacity < 0 || stop.opacity > 1) {
throw new Error(`${label} has invalid gradient stops.`);
}
previous = stop.offset;
}
}
function assertTypography(typography: VisualTextTypography, label: string): void {
assertExactFonts(typography.fonts, `${label}.fonts`);
finite(typography.sizePx, `${label}.sizePx`);
if (typography.sizePx <= 0 || !Number.isSafeInteger(typography.weight) || typography.weight < 1 || typography.weight > 1_000) {
throw new Error(`${label} size or weight is invalid.`);
}
if (!["normal", "italic", "oblique"].includes(typography.style)
|| !["none", "weight", "style", "weight-style"].includes(typography.synthesis)
|| !["auto", "normal", "none"].includes(typography.kerning)
|| !["auto", "ltr", "rtl"].includes(typography.direction)
|| !["horizontal-tb", "vertical-rl", "vertical-lr"].includes(typography.writingMode)
|| !["none", "uppercase", "lowercase", "capitalize"].includes(typography.transform)
|| !["normal", "small-caps", "all-small-caps"].includes(typography.variantCaps)
|| !["baseline", "super", "sub"].includes(typography.verticalAlign)) {
throw new Error(`${label} contains an unsupported typography enum.`);
}
for (const [name, value] of Object.entries({
trackingPx: typography.trackingPx,
wordSpacingPx: typography.wordSpacingPx,
lineHeight: typography.lineHeight,
baselineShiftPx: typography.baselineShiftPx,
indentationPx: typography.indentationPx,
paragraphBeforePx: typography.paragraphBeforePx,
paragraphAfterPx: typography.paragraphAfterPx,
})) finite(value, `${label}.${name}`);
if (typography.lineHeight <= 0 || !Number.isSafeInteger(typography.tabSize) || typography.tabSize <= 0) {
throw new Error(`${label} lineHeight or tabSize is invalid.`);
}
const axes = new Set<string>();
for (const [index, axis] of typography.axes.entries()) {
if (!/^[\x20-\x7e]{4}$/u.test(axis.tag) || axes.has(axis.tag)) throw new Error(`${label}.axes.${index} is invalid.`);
finite(axis.value, `${label}.axes.${index}.value`);
axes.add(axis.tag);
}
const features = new Set<string>();
for (const [index, feature] of typography.features.entries()) {
if (!/^[\x20-\x7e]{4}$/u.test(feature.tag) || features.has(feature.tag)) throw new Error(`${label}.features.${index} is invalid.`);
features.add(feature.tag);
}
const decorations = new Set<string>();
for (const [index, decoration] of typography.decorations.entries()) {
const item = `${label}.decorations.${index}`;
if (!["underline", "overline", "line-through"].includes(decoration.line)
|| !["solid", "double", "dotted", "dashed", "wavy"].includes(decoration.style)
|| decorations.has(decoration.line)) {
throw new Error(`${item} is invalid or repeated.`);
}
decorations.add(decoration.line);
assertColorPaint(decoration.paint, `${item}.paint`);
if (decoration.thicknessPx !== undefined) nonNegative(decoration.thicknessPx, `${item}.thicknessPx`);
if (decoration.offsetPx !== undefined) finite(decoration.offsetPx, `${item}.offsetPx`);
}
}
function assertRunStyle(style: VisualTextRunStyle | undefined, label: string): void {
if (style === undefined) return;
if (style.typography !== undefined) {
const merged = style.typography;
if (merged.fonts !== undefined) assertExactFonts(merged.fonts, `${label}.fonts`);
for (const [name, value] of Object.entries(merged)) {
if (typeof value === "number") finite(value, `${label}.${name}`);
}
}
for (const [index, paint] of (style.paints ?? []).entries()) assertTextPaint(paint, `${label}.paints.${index}`);
}
function inheritedTypography(
base: VisualTextTypography,
style: VisualTextRunStyle | undefined,
): VisualTextTypography {
const override = style?.typography;
if (override === undefined) return base;
const {
fonts: _fonts,
axes: _axes,
features: _features,
decorations: _decorations,
cjk: _cjk,
...scalarOverrides
} = override;
return {
...base,
...scalarOverrides,
fonts: override.fonts ?? base.fonts,
axes: override.axes ?? base.axes,
features: override.features ?? base.features,
decorations: override.decorations ?? base.decorations,
cjk: override.cjk === undefined ? base.cjk : { ...base.cjk, ...override.cjk },
};
}
function assertTextDocument(
document: VisualTextDocument,
typography: VisualTextTypography,
label: string,
): void {
if (document.paragraphs.length === 0) throw new Error(`${label} has no paragraphs.`);
const ids = new Set<string>();
let hasText = false;
for (const [paragraphIndex, paragraph] of document.paragraphs.entries()) {
assertNonEmpty(paragraph.id, `${label}.paragraphs.${paragraphIndex}.id`);
if (ids.has(paragraph.id) || paragraph.inlines.length === 0) throw new Error(`${label} has an invalid paragraph.`);
ids.add(paragraph.id);
assertRunStyle(paragraph.style, `${label}.paragraphs.${paragraphIndex}.style`);
const paragraphTypography = inheritedTypography(typography, paragraph.style);
assertTypography(paragraphTypography, `${label}.paragraphs.${paragraphIndex}.typography`);
for (const [inlineIndex, inline] of paragraph.inlines.entries()) {
assertNonEmpty(inline.id, `${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.id`);
if (ids.has(inline.id)) throw new Error(`${label} repeats inline id ${inline.id}.`);
ids.add(inline.id);
if (inline.kind === "text") {
if (inline.text.length === 0) throw new Error(`${label} contains an empty text run.`);
hasText ||= inline.text.trim().length > 0;
assertRunStyle(inline.style, `${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.style`);
const inlineTypography = inheritedTypography(paragraphTypography, inline.style);
assertTypography(inlineTypography, `${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.typography`);
if (inline.direction !== undefined && !["auto", "ltr", "rtl"].includes(inline.direction)) {
throw new Error(`${label}.paragraphs.${paragraphIndex}.inlines.${inlineIndex}.direction is invalid.`);
}
} else if (inline.kind !== "break") throw new Error(`${label} contains an unsupported inline.`);
}
}
if (!hasText) throw new Error(`${label} contains no visible text.`);
}
function assertBoxDecoration(decoration: VisualTextBoxDecoration, label: string): void {
if (decoration.fill !== undefined) assertColorPaint(decoration.fill, `${label}.fill`);
for (const [name, value] of Object.entries(decoration.paddingPx)) nonNegative(value, `${label}.paddingPx.${name}`);
for (const [name, value] of Object.entries(decoration.radiiPx)) nonNegative(value, `${label}.radiiPx.${name}`);
if (decoration.border !== undefined) {
assertColorPaint(decoration.border.paint, `${label}.border.paint`);
if (!["solid", "dashed", "dotted"].includes(decoration.border.style)) {
throw new Error(`${label}.border.style is invalid.`);
}
for (const [name, value] of Object.entries(decoration.border.widthsPx)) nonNegative(value, `${label}.border.widthsPx.${name}`);
}
for (const [index, shadow] of decoration.shadows.entries()) {
assertColorPaint(shadow.paint, `${label}.shadows.${index}.paint`);
finite(shadow.offsetX, `${label}.shadows.${index}.offsetX`);
finite(shadow.offsetY, `${label}.shadows.${index}.offsetY`);
nonNegative(shadow.blurPx, `${label}.shadows.${index}.blurPx`);
finite(shadow.spreadPx, `${label}.shadows.${index}.spreadPx`);
}
if (decoration.tail !== undefined) {
if (!["top", "right", "bottom", "left"].includes(decoration.tail.side)) {
throw new Error(`${label}.tail.side is invalid.`);
}
finite(decoration.tail.offset, `${label}.tail.offset`);
nonNegative(decoration.tail.widthPx, `${label}.tail.widthPx`);
nonNegative(decoration.tail.heightPx, `${label}.tail.heightPx`);
assertColorPaint(decoration.tail.paint, `${label}.tail.paint`);
}
}
function assertTextPaint(paint: VisualTextPaintLayer, label: string): void {
if (paint.kind === "fill") return assertColorPaint(paint.paint, `${label}.paint`);
if (paint.kind === "stroke") {
assertColorPaint(paint.paint, `${label}.paint`);
if (!["inside", "center", "outside"].includes(paint.placement)) {
throw new Error(`${label}.placement is invalid.`);
}
return nonNegative(paint.widthPx, `${label}.widthPx`);
}
if (paint.kind === "shadow") {
assertColorPaint(paint.paint, `${label}.paint`);
finite(paint.offsetX, `${label}.offsetX`);
finite(paint.offsetY, `${label}.offsetY`);
nonNegative(paint.blurPx, `${label}.blurPx`);
finite(paint.spreadPx, `${label}.spreadPx`);
return;
}
if (paint.kind === "glow") {
assertColorPaint(paint.paint, `${label}.paint`);
nonNegative(paint.blurPx, `${label}.blurPx`);
finite(paint.spreadPx, `${label}.spreadPx`);
return;
}
if (paint.kind !== "box") throw new Error(`${label} has an unsupported Paint kind.`);
if (paint.continuity === "joined" && !["line", "word", "grapheme"].includes(paint.target)) {
throw new Error(`${label} joined continuity is invalid for ${paint.target}.`);
}
assertBoxDecoration(paint.decoration, `${label}.decoration`);
}
function assertTextFlow(flow: VisualTextFlow, label: string): void {
if (!(["hug", "fixed"] as const).includes(flow.inlineSize)
|| !(["hug", "fixed"] as const).includes(flow.blockSize)
|| !(["start", "center", "end", "justify"] as const).includes(flow.inlineAlign)
|| !(["start", "center", "end"] as const).includes(flow.blockAlign)
|| !(["none", "word", "grapheme"] as const).includes(flow.wrap)
|| !(["visible", "clip", "ellipsis", "shrink"] as const).includes(flow.overflow)
|| !(["line-box", "cap-height", "ink"] as const).includes(flow.metricEdge)) {
throw new Error(`${label} contains an unsupported flow enum.`);
}
if (flow.form.kind === "point" && (flow.inlineSize !== "hug" || flow.blockSize !== "hug" || flow.wrap !== "none")) {
throw new Error(`${label} Point Text must hug both axes and cannot soft-wrap.`);
}
for (const [name, value] of Object.entries(flow.paddingPx)) nonNegative(value, `${label}.paddingPx.${name}`);
if (!Number.isSafeInteger(flow.columns) || flow.columns <= 0) throw new Error(`${label}.columns must be positive.`);
nonNegative(flow.columnGapPx, `${label}.columnGapPx`);
if (flow.maxLines !== undefined && (!Number.isSafeInteger(flow.maxLines) || flow.maxLines <= 0)) {
throw new Error(`${label}.maxLines must be positive.`);
}
if (flow.maxLines !== undefined && flow.overflow !== "ellipsis" && flow.overflow !== "shrink") {
throw new Error(`${label}.maxLines is valid only for ellipsis or shrink.`);
}
if (flow.overflow === "shrink") {
if (flow.minimumScale === undefined || !Number.isFinite(flow.minimumScale) || flow.minimumScale <= 0 || flow.minimumScale > 1) {
throw new Error(`${label}.minimumScale is required in (0, 1] for shrink.`);
}
} else if (flow.minimumScale !== undefined) throw new Error(`${label}.minimumScale is valid only for shrink.`);
}
function assertTextSequences(
sequences: readonly VisualTextSequenceAnimation[],
_durationFrames: number,
label: string,
): void {
const ids = new Set<string>();
for (const [index, sequence] of sequences.entries()) {
const item = `${label}.${index}`;
assertNonEmpty(sequence.id, `${item}.id`);
if (ids.has(sequence.id)) throw new Error(`${label} repeats ${sequence.id}.`);
ids.add(sequence.id);
if (!(["paragraph", "line", "run", "word", "grapheme"] as const).includes(sequence.unit)
|| !(["forward", "reverse", "random"] as const).includes(sequence.order)) {
throw new Error(`${item} unit or order is invalid.`);
}
if (!Number.isSafeInteger(sequence.range.start) || !Number.isSafeInteger(sequence.range.endExclusive)
|| sequence.range.start < 0 || sequence.range.endExclusive <= sequence.range.start
|| !Number.isSafeInteger(sequence.startFrame) || sequence.startFrame < 0
|| !Number.isSafeInteger(sequence.unitDurationFrames) || sequence.unitDurationFrames <= 0
|| !Number.isSafeInteger(sequence.staggerFrames) || sequence.staggerFrames < 0
|| !Number.isSafeInteger(sequence.cycles) || sequence.cycles <= 0
|| (sequence.seed !== undefined && !Number.isSafeInteger(sequence.seed))) {
throw new Error(`${item} frame domain or range is invalid.`);
}
if ((sequence.order === "random") !== (sequence.seed !== undefined)) {
throw new Error(`${item} random order requires one explicit seed, and other orders forbid it.`);
}
if (sequence.keyframes.length < 2 || sequence.keyframes[0]?.atProgress !== 0 || sequence.keyframes.at(-1)?.atProgress !== 1) {
throw new Error(`${item} keyframes must cover progress [0, 1].`);
}
let previous = -1;
for (const [frameIndex, keyframe] of sequence.keyframes.entries()) {
if (!Number.isFinite(keyframe.atProgress) || keyframe.atProgress <= previous || keyframe.atProgress < 0 || keyframe.atProgress > 1) {
throw new Error(`${item}.keyframes.${frameIndex} progress is invalid.`);
}
assertStyle(keyframe.style, `${item}.keyframes.${frameIndex}.style`);
if (keyframe.style.some((declaration) => !ANIMATABLE_TEXT_UNIT_STYLES.has(declaration.name))) {
throw new Error(`${item}.keyframes.${frameIndex} animates an unsupported text-unit property.`);
}
previous = keyframe.atProgress;
}
}
}
function assertPathCommands(path: readonly VisualVectorPathCommand[], label: string): void {
if (path.length < 2 || path[0]?.kind !== "move") throw new Error(`${label} must begin with move and contain drawable geometry.`);
if (!path.some((command) => command.kind === "line" || command.kind === "quadratic" || command.kind === "cubic")) {
throw new Error(`${label} contains no drawable geometry.`);
}
for (const [index, command] of path.entries()) {
for (const [name, value] of Object.entries(command)) {
if (name !== "kind") finite(value as number, `${label}.${index}.${name}`);
}
}
}
function assertAnimation(animation: VisualAnimation | undefined, _durationFrames: number, label: string): void {
if (animation === undefined) return;
if (animation.keyframes.length < 2) throw new Error(`${label} animation must contain at least two keyframes.`);
let previous = -1;
for (const [index, keyframe] of animation.keyframes.entries()) {
if (
!Number.isSafeInteger(keyframe.atFrame)
|| keyframe.atFrame < 0
|| keyframe.atFrame <= previous
) {
throw new Error(`${label} animation keyframe ${index + 1} has an invalid frame offset.`);
}
if (
keyframe.easing !== undefined
&& !["linear", "ease-in", "ease-out", "ease-in-out"].includes(keyframe.easing)
) {
throw new Error(`${label} animation keyframe ${index + 1} has an invalid easing.`);
}
if (keyframe.style.length === 0) throw new Error(`${label} animation keyframe ${index + 1} has no style.`);
assertStyle(keyframe.style, `${label}.animation.${index + 1}`);
for (const declaration of keyframe.style) {
if (!ANIMATABLE_LOCAL_STYLES.has(declaration.name)) {
throw new Error(`${label} animation cannot change ${declaration.name}.`);
}
}
previous = keyframe.atFrame;
}
}
function assertPresent(present: VisualPresent, timeline: Timeline | undefined, trackId: string): void {
const totalFrames = timeline === undefined ? Number.MAX_SAFE_INTEGER : timelineFrameCount(timeline);
assertNonEmpty(present.id, `${trackId} Present id`);
if (present.subjectId !== undefined) assertNonEmpty(present.subjectId, `${trackId}.${present.id} subjectId`);
assertFrameSpan(present.span, totalFrames, `${trackId}.${present.id}.span`);
let previousEnd = present.span.startFrame;
for (const span of present.visibility ?? []) {
assertFrameSpan(span, present.span.endFrameExclusive, `${trackId}.${present.id}.visibility`);
if (span.startFrame < previousEnd) throw new Error(`${trackId}.${present.id} visibility must be ordered within its span.`);
previousEnd = span.endFrameExclusive;
}
if (!Number.isSafeInteger(present.order) || present.order < 0) {
throw new Error(`${trackId}.${present.id} has invalid local order.`);
}
if (!Number.isSafeInteger(present.z)) throw new Error(`${trackId}.${present.id} has invalid z.`);
if (present.elements.length === 0) throw new Error(`${trackId}.${present.id} must contain an element.`);
const elements = new Map<string, VisualElement>();
const roots: VisualElement[] = [];
const orders = new Set<number>();
for (const element of present.elements) {
assertNonEmpty(element.id, `${trackId}.${present.id} element id`);
if (elements.has(element.id)) throw new Error(`${trackId}.${present.id} has duplicate element ${element.id}.`);
if (!Number.isSafeInteger(element.order) || element.order < 0 || orders.has(element.order)) {
throw new Error(`${trackId}.${present.id}.${element.id} has invalid or duplicate order.`);
}
orders.add(element.order);
elements.set(element.id, element);
if (element.parent === undefined) roots.push(element);
assertStyle(element.style, `${trackId}.${present.id}.${element.id}`);
assertAttributes(element.attributes, `${trackId}.${present.id}.${element.id}`);
assertAnimation(
element.animation,
present.span.endFrameExclusive - present.span.startFrame,
`${trackId}.${present.id}.${element.id}`,
);
if (element.kind === "program") {
assertNonEmpty(element.program.format, `${element.id}.program.format`);
if (element.program.payload === null || typeof element.program.payload !== "object" || Array.isArray(element.program.payload)) throw new Error("Visual program payload must be an object.");
canonicalStringify(element.program.payload);
for (const artifact of element.program.artifacts) assertMediaArtifact(artifact, `${element.id}.program.artifacts`);
}
if (element.kind === "image" || element.kind === "video") {
assertMediaArtifact(element.artifact, `${trackId}.${present.id}.${element.id}.artifact`);
if (!element.artifact.mediaType.startsWith(`${element.kind}/`)) {
throw new Error(`${trackId}.${present.id}.${element.id} media kind does not match its Artifact.`);
}
if (element.kind === "video") {
if (element.animation !== undefined) {
throw new Error(`${trackId}.${present.id}.${element.id} source time and animation must live on separate owned elements.`);
}
assertSourceTime(element.sourceTime, present.span.endFrameExclusive - present.span.startFrame,
`${trackId}.${present.id}.${element.id}.sourceTime`);
}
}
if (element.kind === "text") {
const label = `${trackId}.${present.id}.${element.id}`;
assertExactFonts(element.fonts, `${label}.fonts`);
const ownedFontStyles = new Set(["font", "font-family", "font-style", "font-synthesis", "font-weight"]);
if (element.style.some((declaration) => ownedFontStyles.has(declaration.name))) {
throw new Error(`${label} exact fonts conflict with a raw font style.`);
}
for (const [index, paint] of (element.paints ?? []).entries()) {
assertTextPaint(paint, `${label}.paints.${index}`);
// Box Paint decorates a laid-out run, and this element has no layout to decorate.
if (paint.kind === "box") throw new Error(`${label}.paints.${index} is Box Paint on a plain text element.`);
}
// Two ways to say the same thing render twice: the declared Paint draws the glyph, and the
// style would draw it again underneath.
const paintedStyles = new Set(["-webkit-text-stroke", "-webkit-text-stroke-color", "-webkit-text-stroke-width", "paint-order"]);
if (element.paints !== undefined && element.style.some((declaration) => paintedStyles.has(declaration.name))) {
throw new Error(`${label} declares glyph Paint beside a raw stroke style.`);
}
}
if (element.kind === "text-flow" || element.kind === "path-text") {
const label = `${trackId}.${present.id}.${element.id}`;
assertTextDocument(element.document, element.typography, `${label}.document`);
assertTypography(element.typography, `${label}.typography`);
const boxKeys = new Set<string>();
for (const [index, paint] of element.paints.entries()) {
assertTextPaint(paint, `${label}.paints.${index}`);
if (paint.kind === "box") {
const key = `${paint.target}:${paint.continuity}`;
if (boxKeys.has(key)) throw new Error(`${label} repeats Box Paint ${key}.`);
boxKeys.add(key);
}
}
assertTextSequences(element.sequences, present.span.endFrameExclusive - present.span.startFrame, `${label}.sequences`);
if (element.kind === "text-flow") assertTextFlow(element.flow, `${label}.flow`);
else {
assertPathCommands(element.path, `${label}.path`);
if (!(["left", "right"] as const).includes(element.side)
|| !(["follow", "upright"] as const).includes(element.orientation)
|| !(["start", "center", "end"] as const).includes(element.align)
|| !(["visible", "clip"] as const).includes(element.overflow)) {
throw new Error(`${label} contains an unsupported Path Text enum.`);
}
nonNegative(element.startMarginPx, `${label}.startMarginPx`);
nonNegative(element.endMarginPx, `${label}.endMarginPx`);
if (element.marginAnimation !== undefined) {
const frames = element.marginAnimation.keyframes;
if (frames.length < 2) throw new Error(`${label}.marginAnimation requires two keyframes.`);
let previous = -1;
for (const [index, keyframe] of frames.entries()) {
if (!Number.isSafeInteger(keyframe.atFrame) || keyframe.atFrame <= previous) {
throw new Error(`${label}.marginAnimation.${index} has an invalid frame.`);
}
nonNegative(keyframe.startMarginPx, `${label}.marginAnimation.${index}.startMarginPx`);
previous = keyframe.atFrame;
}
}
}
}
if (element.kind === "surface") {
assertCompositableSurfaceRef(element.surface, `${trackId}.${present.id}.${element.id}.surface`);
if (element.surface.timing.kind === "still" && element.sourceTime !== undefined) {
throw new Error(`${trackId}.${present.id}.${element.id} still Surface cannot have source time.`);
}
if (element.sourceTime !== undefined) {
if (element.animation !== undefined) {
throw new Error(`${trackId}.${present.id}.${element.id} source time and animation must live on separate owned elements.`);
}
if (element.surface.timing.kind !== "frames"
|| element.sourceTime.sourceFrameCount !== element.surface.timing.frameCount
|| element.sourceTime.sourceFrameRate.numerator !== element.surface.timing.frameRate.numerator
|| element.sourceTime.sourceFrameRate.denominator !== element.surface.timing.frameRate.denominator) {
throw new Error(`${trackId}.${present.id}.${element.id} Surface source time differs from its typed timing.`);
}
assertSourceTime(element.sourceTime, present.span.endFrameExclusive - present.span.startFrame,
`${trackId}.${present.id}.${element.id}.sourceTime`);
}
if (element.surface.timing.kind === "frames") {
if (element.sourceTime === undefined) throw new Error(`${trackId}.${present.id}.${element.id} timed Surface requires source time.`);
}
}
if (element.kind === "mask") {
if (!["alpha", "luminance"].includes(element.mode)
|| element.maskElement === element.contentElement) {
throw new Error(`${trackId}.${present.id}.${element.id} has an invalid local mask.`);
}
}
}
if (roots.length !== 1) throw new Error(`${trackId}.${present.id} must contain exactly one root element.`);
for (const element of present.elements) {
if (element.parent !== undefined && !elements.has(element.parent)) {
throw new Error(`${trackId}.${present.id}.${element.id} references a foreign parent.`);
}
if (element.parent !== undefined && !["box", "mask", "program"].includes(elements.get(element.parent)?.kind ?? "")) {
throw new Error(`${trackId}.${present.id}.${element.id} must have a box, mask or program parent.`);
}
const visited = new Set<string>();
let cursor: VisualElement | undefined = element;
while (cursor?.parent !== undefined) {
if (visited.has(cursor.id)) throw new Error(`${trackId}.${present.id} contains an element cycle.`);
visited.add(cursor.id);
cursor = elements.get(cursor.parent);
}
}
for (const element of present.elements) {
if (element.kind !== "mask") continue;
const direct = present.elements.filter((candidate) => candidate.parent === element.id);
if (direct.length !== 2
|| !direct.some((candidate) => candidate.id === element.maskElement)
|| !direct.some((candidate) => candidate.id === element.contentElement)) {
throw new Error(`${trackId}.${present.id}.${element.id} must own exactly its declared mask and content roots.`);
}
const maskRoot = direct.find((candidate) => candidate.id === element.maskElement)!;
if (!["text", "text-flow", "path-text", "image", "surface"].includes(maskRoot.kind)
|| (maskRoot.kind === "surface" && maskRoot.surface.timing.kind !== "still")
|| present.elements.some((candidate) => candidate.parent === maskRoot.id)) {
throw new Error(`${trackId}.${present.id}.${element.id} mask source must be one terminal owned text, image or still Surface.`);
}
}
}
function normalizeStyle(style: readonly VisualStyleDeclaration[]): VisualStyleDeclaration[] {
return [...style]
.map((item) => ({ name: item.name, value: item.value }))
.sort((left, right) => left.name.localeCompare(right.name));
}
function normalizeAttributes(attributes: readonly VisualAttribute[]): readonly VisualAttribute[] {
return [...attributes]
.map((item) => ({ name: item.name, value: item.value }))
.sort((left, right) => left.name.localeCompare(right.name));
}
function normalizeAnimation(animation: VisualAnimation): VisualAnimation {
return {
keyframes: [...animation.keyframes]
.map((keyframe) => ({
atFrame: keyframe.atFrame,
...(keyframe.easing === undefined ? {} : { easing: keyframe.easing }),
style: normalizeStyle(keyframe.style),
}))
.sort((left, right) => left.atFrame - right.atFrame),
};
}
function normalizeElement(element: VisualElement): VisualElement {
const common = {
id: element.id,
...(element.parent === undefined ? {} : { parent: element.parent }),
order: element.order,
style: normalizeStyle(element.style),
...(element.attributes === undefined ? {} : { attributes: normalizeAttributes(element.attributes) }),
...(element.animation === undefined ? {} : { animation: normalizeAnimation(element.animation) }),
};
if (element.kind === "box") return { ...common, kind: "box" };
if (element.kind === "program") return { ...common, kind: "program", program: structuredClone(element.program) };
if (element.kind === "mask") return {
...common,
kind: "mask",
mode: element.mode,
maskElement: element.maskElement,
contentElement: element.contentElement,
};
if (element.kind === "text") {
return {
...common,
kind: "text",
text: element.text,
fonts: element.fonts.map((font) => ({
sources: font.sources.map((source) => ({
artifact: { ...source.artifact },
...(source.unicodeRange === undefined ? {} : { unicodeRange: source.unicodeRange }),
})),
weight: font.weight,
style: font.style,
})),
...(element.paints === undefined ? {} : { paints: structuredClone(element.paints) as VisualTextPaintLayer[] }),
};
}
if (element.kind === "text-flow" || element.kind === "path-text") {
const copy = structuredClone(element);
return {
...copy,
...common,
kind: element.kind,
sequences: element.sequences.map((sequence) => ({
...sequence,
range: { ...sequence.range },
keyframes: sequence.keyframes.map((keyframe) => ({
...keyframe,
style: normalizeStyle(keyframe.style),
})),
})),
} as VisualTextFlowElement | VisualPathTextElement;
}
if (element.kind === "surface") {
return {
...common,
kind: "surface",
surface: {
...element.surface,
artifact: { ...element.surface.artifact },
timing: element.surface.timing.kind === "still"
? { kind: "still" }
: { ...element.surface.timing, frameRate: { ...element.surface.timing.frameRate } },
},
...(element.sourceTime === undefined ? {} : { sourceTime: {
sourceFrameRate: { ...element.sourceTime.sourceFrameRate },
sourceFrameCount: element.sourceTime.sourceFrameCount,
pieces: element.sourceTime.pieces.map((piece) => ({
target: { ...piece.target }, sourceAtStart: { ...piece.sourceAtStart }, rate: { ...piece.rate },
...(piece.wrap === undefined ? {} : { wrap: { ...piece.wrap } }),
})),
} }),
};
}
// Spreading an absent artifact produced `{}`, which is not an artifact and is not nothing either:
// the field the author actually wrote was dropped without a word, and the refusal came one call
// later from the identity check, naming `.artifact` — a field they had not typed.
if (element.artifact === undefined) {
throw new Error(`${element.id} is a ${element.kind} element with no artifact.`);
}
if (element.kind === "image") return { ...common, kind: "image", artifact: { ...element.artifact } };
return {
...common,
kind: "video",
artifact: { ...element.artifact },
sourceTime: {
sourceFrameRate: { ...element.sourceTime.sourceFrameRate },
sourceFrameCount: element.sourceTime.sourceFrameCount,
pieces: element.sourceTime.pieces.map((piece) => ({
target: { ...piece.target }, sourceAtStart: { ...piece.sourceAtStart }, rate: { ...piece.rate },
...(piece.wrap === undefined ? {} : { wrap: { ...piece.wrap } }),
})),
},
...(element.muted === undefined ? {} : { muted: element.muted }),
};
}
function visualTrackContent(value: Omit<VisualTrack, "kind">): VisualTrack {
return {
kind: "visual",
timelineId: value.timelineId,
visualIr: value.visualIr,
id: value.id,
presents: [...value.presents]
.map((present) => ({
id: present.id,
order: present.order,
z: present.z,
...(present.subjectId === undefined ? {} : { subjectId: present.subjectId }),
span: { ...present.span },
...(present.visibility === undefined ? {} : { visibility: present.visibility.map(span => ({ ...span })) }),
elements: [...present.elements].map(normalizeElement).sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)),
}))
.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)),
};
}
function audioTrackContent(value: Omit<AudioTrack, "kind">): AudioTrack {
return {
kind: "audio",
timelineId: value.timelineId,
id: value.id,
clips: [...value.clips]
.map((clip) => ({
id: clip.id,
...(clip.subjectId === undefined ? {} : { subjectId: clip.subjectId }),
artifact: { ...clip.artifact },
target: { ...clip.target },
sourceTime: {
sourceSampleFrames: clip.sourceTime.sourceSampleFrames,
pieces: clip.sourceTime.pieces.map((piece) => ({
target: { ...piece.target },
sourceAtStart: { ...piece.sourceAtStart },
rate: { ...piece.rate },
...(piece.wrap === undefined ? {} : { wrap: { ...piece.wrap } }),
})),
},
gain: clip.gain,
fadeInSamples: clip.fadeInSamples,
fadeOutSamples: clip.fadeOutSamples,
...(clip.gainEnvelope === undefined ? {} : { gainEnvelope: clip.gainEnvelope.map(point => ({ ...point })) }),
...(clip.audibility === undefined ? {} : { audibility: clip.audibility.map(span => ({ ...span })) }),
}))
.sort((a, b) => a.target.startSample - b.target.startSample || a.id.localeCompare(b.id)),
};
}
export function sealVisualTrack(value: Omit<VisualTrack, "kind">): VisualTrack {
return visualTrackContent(value);
}
export function sealAudioTrack(value: Omit<AudioTrack, "kind">): AudioTrack {
return audioTrackContent(value);
}
export function assertVisualTrackIdentity(track: VisualTrack, timeline?: Timeline): void {
if (timeline !== undefined) assertTimelineIdentity(timeline);
if (track.kind !== "visual") throw new Error("VisualTrack kind is invalid.");
if (track.visualIr !== VISUAL_IR_V1) throw new Error("Unsupported VisualTrack visual IR.");
assertNonEmpty(track.timelineId, "VisualTrack timelineId");
if (timeline !== undefined && track.timelineId !== timeline.id) {
throw new Error(`VisualTrack ${track.id} belongs to Timeline ${track.timelineId}, not ${timeline.id}.`);
}
assertNonEmpty(track.id, "VisualTrack id");
const presentIds = new Set<string>();
for (const present of track.presents) {
if (presentIds.has(present.id)) throw new Error(`${track.id} has duplicate Present ${present.id}.`);
presentIds.add(present.id);
assertPresent(present, timeline, track.id);
}
}
export function assertAudioTrackIdentity(track: AudioTrack, timeline?: Timeline): void {
if (timeline !== undefined) assertTimelineIdentity(timeline);
if (track.kind !== "audio") throw new Error("AudioTrack kind is invalid.");
assertNonEmpty(track.timelineId, "AudioTrack timelineId");
if (timeline !== undefined && track.timelineId !== timeline.id) {
throw new Error(`AudioTrack ${track.id} belongs to Timeline ${track.timelineId}, not ${timeline.id}.`);
}
assertNonEmpty(track.id, "AudioTrack id");
const totalSamples = timeline === undefined
? Number.MAX_SAFE_INTEGER
: timelineSampleFrames(timeline, 48_000);
const clipIds = new Set<string>();
for (const clip of track.clips) {
if (clipIds.has(clip.id)) throw new Error(`${track.id} has duplicate clip ${clip.id}.`);
clipIds.add(clip.id);
assertNonEmpty(clip.id, `${track.id} clip id`);
if (clip.subjectId !== undefined) assertNonEmpty(clip.subjectId, `${track.id}.${clip.id} subjectId`);
assertAudioArtifact(clip.artifact, `${track.id}.${clip.id}.artifact`);
if (!Number.isSafeInteger(clip.target.startSample) || clip.target.startSample < 0
|| !Number.isSafeInteger(clip.target.endSampleExclusive)
|| clip.target.endSampleExclusive <= clip.target.startSample
|| clip.target.endSampleExclusive > totalSamples) {
throw new Error(`${track.id}.${clip.id} target sample interval is outside Timeline.`);
}
assertAudioSourceTime(clip.sourceTime, clip.target.endSampleExclusive - clip.target.startSample,
`${track.id}.${clip.id}.sourceTime`);
if (!Number.isFinite(clip.gain) || clip.gain < 0 || clip.gain > 64) {
throw new Error(`${track.id}.${clip.id} gain is invalid.`);
}
assertAudioLevelAutomation(clip, clip.target, totalSamples);
const targetLength = clip.target.endSampleExclusive - clip.target.startSample;
if (!Number.isSafeInteger(clip.fadeInSamples) || clip.fadeInSamples < 0 || clip.fadeInSamples > targetLength
|| !Number.isSafeInteger(clip.fadeOutSamples) || clip.fadeOutSamples < 0
|| clip.fadeOutSamples > targetLength) {
throw new Error(`${track.id}.${clip.id} fades are invalid.`);
}
}
}
function assertAudioSourceTimeRational(value: AudioSourceTimeRational, label: string, positive = false): void {
if (!Number.isSafeInteger(value.numerator) || (positive ? value.numerator <= 0 : value.numerator < 0)
|| !Number.isSafeInteger(value.denominator) || value.denominator <= 0) {
throw new Error(`${label} is invalid.`);
}
}
function compareAudioRational(value: AudioSourceTimeRational, integer: number): number {
const difference = BigInt(value.numerator) - BigInt(integer) * BigInt(value.denominator);
return difference < 0n ? -1 : difference > 0n ? 1 : 0;
}
function compareAudioSourceAtEnd(piece: AudioSourceTimePiece, integer: number): number {
const length = piece.target.endSampleExclusive - piece.target.startSample;
const numerator = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ BigInt(length) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
const denominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
const difference = numerator - BigInt(integer) * denominator;
return difference < 0n ? -1 : difference > 0n ? 1 : 0;
}
function assertAudioSourceTime(value: AudioSourceTimeMap, targetSamples: number, label: string): void {
if (!Number.isSafeInteger(value.sourceSampleFrames) || value.sourceSampleFrames <= 0
|| !Array.isArray(value.pieces) || value.pieces.length === 0) throw new Error(`${label} is invalid.`);
let previousEnd = 0;
for (const [index, piece] of value.pieces.entries()) {
const item = `${label}.pieces.${index}`;
if (!Number.isSafeInteger(piece.target.startSample) || piece.target.startSample < previousEnd
|| !Number.isSafeInteger(piece.target.endSampleExclusive)
|| piece.target.endSampleExclusive <= piece.target.startSample
|| piece.target.endSampleExclusive > targetSamples) throw new Error(`${item}.target is invalid.`);
assertAudioSourceTimeRational(piece.sourceAtStart, `${item}.sourceAtStart`);
assertAudioSourceTimeRational(piece.rate, `${item}.rate`, true);
if (piece.sourceAtStart.numerator % piece.sourceAtStart.denominator !== 0) {
throw new Error(`${item}.sourceAtStart must resolve to an exact source-sample boundary.`);
}
if (piece.wrap === undefined) {
const sourceEndNumerator = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ BigInt(piece.target.endSampleExclusive - piece.target.startSample)
* BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
const sourceEndDenominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
if (sourceEndNumerator % sourceEndDenominator !== 0n) {
throw new Error(`${item} must end on an exact source-sample boundary.`);
}
if (compareAudioRational(piece.sourceAtStart, value.sourceSampleFrames) >= 0
|| compareAudioSourceAtEnd(piece, value.sourceSampleFrames) > 0) {
throw new Error(`${item} leaves the source domain.`);
}
} else if (!Number.isSafeInteger(piece.wrap.startSample) || piece.wrap.startSample < 0
|| !Number.isSafeInteger(piece.wrap.endSampleExclusive)
|| piece.wrap.endSampleExclusive <= piece.wrap.startSample
|| piece.wrap.endSampleExclusive > value.sourceSampleFrames
|| compareAudioRational(piece.sourceAtStart, piece.wrap.startSample) < 0
|| compareAudioRational(piece.sourceAtStart, piece.wrap.endSampleExclusive) >= 0) {
throw new Error(`${item}.wrap is invalid.`);
}
previousEnd = piece.target.endSampleExclusive;
}
}
function trackKey(track: Track): string {
return `${track.kind}\u0000${track.id}`;
}
function compositionContent(value: Composition): Composition {
return {
id: value.id,
canvas: { ...value.canvas },
tracks: [...value.tracks].map((track) => structuredClone(track)).sort((a, b) => trackKey(a).localeCompare(trackKey(b))),
};
}
export function sealComposition(value: Composition): Composition {
return compositionContent(value);
}
export function assertCompositionIdentity(composition: Composition, timeline?: Timeline): void {
assertNonEmpty(composition.id, "Composition id");
if (timeline !== undefined) assertTimelineIdentity(timeline);
if (
!Number.isSafeInteger(composition.canvas.width)
|| composition.canvas.width <= 0
|| !Number.isSafeInteger(composition.canvas.height)
|| composition.canvas.height <= 0
|| !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(composition.canvas.clearColor)
) {
throw new Error("Composition canvas is invalid.");
}
const ids = new Set<string>();
for (const track of composition.tracks) {
if (ids.has(track.id)) throw new Error(`Composition contains duplicate Track id ${track.id}.`);
ids.add(track.id);
if (track.kind === "visual") {
assertVisualTrackIdentity(track, timeline);
} else {
assertAudioTrackIdentity(track, timeline);
}
}
}