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 { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import {
assertFontArtifactRef,
verifySynchronizedMedia,
} from "@hypit/media";
import type { SynchronizedMedia } from "@hypit/media";
import { canonicalize, isResourceId } from "@hypit/hypit/protocol";
import { verifyText } from "@hypit/hypit/text";
import type { Text } from "@hypit/hypit/text";
import { assertSpatialFrame } from "@hypit/spatial";
import type { SpatialFrame } from "@hypit/spatial";
import {
assertTemporalInstantFor,
assertTemporalWindowFor,
resolveTriggeredSchedule,
} from "@hypit/temporal";
import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
import type {
ColumnItem,
ColumnItemSet,
ColumnItemSpec,
ColumnProgram,
ColumnSchedule,
ColumnStyle,
ColumnWindowSet,
RankingBoardPaint,
RankingHeader,
RankingItemSpec,
RankingItemSpecSet,
RankingTextItemShell,
RankingMotionStyle,
RankingSchedule,
RankingSoundEvent,
RankingSoundEventPlan,
RankingSoundSet,
RankingSoundStyle,
RankingTextStyle,
RankingVariant,
RankingWindowSet,
TierBoardSchedule,
TierBoardWindowSet,
TriggeredRankingCandidateSet,
TriggeredRankingSchedule,
TierBoardItem,
TierBoardItemSet,
TierBoardItemSpec,
TierBoardProgram,
TierBoardStyle,
TopThreeItem,
TopThreeItemSet,
TopThreeItemSpec,
TopThreeProgram,
TopThreeStyle,
} from "./types.js";
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
}
function identity(value: string, label: string): void {
assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
}
function frame(value: number, label: string): void {
assert(Number.isSafeInteger(value) && value >= 0, `${label} must be a non-negative frame.`);
}
function color(value: string, label: string): void {
assert(value === "transparent" || /^#[0-9a-f]{3,8}$/iu.test(value), `${label} must be a hexadecimal color or transparent.`);
}
function finite(value: number, label: string): void {
assert(Number.isFinite(value), `${label} must be finite.`);
}
function nonNegative(value: number, label: string): void {
finite(value, label);
assert(value >= 0, `${label} must be non-negative.`);
}
function positive(value: number, label: string): void {
finite(value, label);
assert(value > 0, `${label} must be positive.`);
}
function integer(value: number, label: string, minimum = 0): void {
assert(Number.isSafeInteger(value) && value >= minimum, `${label} must be an integer >= ${minimum}.`);
}
function stacking(value: number, label: string): void {
assert(Number.isSafeInteger(value), `${label} must be an integer.`);
}
function assertBlobImage(value: { readonly resource: string; readonly size: number; readonly mediaType: string }, label: string): void {
assert(isResourceId(value.resource) && Number.isSafeInteger(value.size) && value.size >= 0
&& /^image\//u.test(value.mediaType), `${label} must be an image Artifact.`);
}
export function assertRankingHeader(value: RankingHeader): void {
identity(value.id, "RankingHeader.id");
assert(["tier-board", "column", "top-three"].includes(value.variant),
"RankingHeader.variant is invalid.");
}
export function sealRankingHeader(value: RankingHeader): RankingHeader {
assertRankingHeader(value);
return canonicalize(value) as unknown as RankingHeader;
}
export function assertRankingTextStyle(value: RankingTextStyle, label: string): void {
assert(value.fonts.length > 0, `${label}.fonts is empty.`);
for (const [index, fontValue] of value.fonts.entries()) assertFontArtifactRef(fontValue, `${label}.fonts.${index}`);
positive(value.sizePx, `${label}.sizePx`);
integer(value.weight, `${label}.weight`, 1);
assert(value.weight <= 1_000, `${label}.weight exceeds 1000.`);
color(value.color, `${label}.color`);
positive(value.lineHeight, `${label}.lineHeight`);
}
export function assertRankingBoardPaint(value: RankingBoardPaint, label: string): void {
color(value.background, `${label}.background`);
color(value.borderColor, `${label}.borderColor`);
nonNegative(value.borderWidthPx, `${label}.borderWidthPx`);
nonNegative(value.radiusPx, `${label}.radiusPx`);
finite(value.shadow.offsetX, `${label}.shadow.offsetX`);
finite(value.shadow.offsetY, `${label}.shadow.offsetY`);
nonNegative(value.shadow.blurPx, `${label}.shadow.blurPx`);
finite(value.shadow.spreadPx, `${label}.shadow.spreadPx`);
color(value.shadow.color, `${label}.shadow.color`);
}
export function assertRankingMotionStyle(value: RankingMotionStyle, label: string): void {
integer(value.appearFrames, `${label}.appearFrames`, 1);
integer(value.moveFrames, `${label}.moveFrames`, 1);
assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.easing), `${label}.easing is invalid.`);
}
export function assertRankingSoundStyle(value: RankingSoundStyle): void {
for (const [name, gain] of [["appearGain", value.appearGain], ["moveGain", value.moveGain]] as const) {
nonNegative(gain, `RankingSoundStyle.${name}`);
assert(gain <= 64, `RankingSoundStyle.${name} exceeds 64.`);
}
integer(value.fadeFrames, "RankingSoundStyle.fadeFrames");
}
function assertCommonStyle(input: {
readonly text: RankingTextStyle;
readonly motion: RankingMotionStyle;
readonly iconSizePx: number;
readonly iconRadiusPx: number;
readonly iconFit: "contain" | "cover";
readonly boardStackingOrder: number;
readonly itemStackingOrder: number;
}, label: string): void {
assertRankingTextStyle(input.text, `${label}.text`);
assertRankingMotionStyle(input.motion, `${label}.motion`);
positive(input.iconSizePx, `${label}.iconSizePx`);
nonNegative(input.iconRadiusPx, `${label}.iconRadiusPx`);
assert(input.iconFit === "contain" || input.iconFit === "cover", `${label}.iconFit is invalid.`);
stacking(input.boardStackingOrder, `${label}.boardStackingOrder`);
stacking(input.itemStackingOrder, `${label}.itemStackingOrder`);
}
export function assertTierBoardStyle(value: TierBoardStyle): void {
assert(value.fonts.length > 0, "TierBoardStyle.fonts is empty.");
value.fonts.forEach((fontValue, index) => assertFontArtifactRef(fontValue, `TierBoardStyle.fonts.${index}`));
color(value.labelTextColor, "TierBoardStyle.labelTextColor");
positive(value.labelSizeRatio, "TierBoardStyle.labelSizeRatio");
positive(value.labelLineHeight, "TierBoardStyle.labelLineHeight");
color(value.boardColor, "TierBoardStyle.boardColor");
color(value.borderColor, "TierBoardStyle.borderColor");
nonNegative(value.borderWidthPx, "TierBoardStyle.borderWidthPx");
if (value.labelWidthRatio !== undefined) {
assert(Number.isFinite(value.labelWidthRatio) && value.labelWidthRatio >= 0.08 && value.labelWidthRatio <= 0.3,
"TierBoardStyle.labelWidthRatio must be between 0.08 and 0.3.");
}
for (const [name, coordinate] of Object.entries(value.stagePoint)) {
assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1,
`TierBoardStyle.stagePoint.${name} must be between 0 and 1.`);
}
positive(value.stageSizePx, "TierBoardStyle.stageSizePx");
nonNegative(value.iconRadiusRatio, "TierBoardStyle.iconRadiusRatio");
assert(value.iconFit === "contain" || value.iconFit === "cover", "TierBoardStyle.iconFit is invalid.");
integer(value.motion.appearFrames, "TierBoardStyle.motion.appearFrames", 1);
integer(value.motion.moveFrames, "TierBoardStyle.motion.moveFrames", 1);
stacking(value.boardStackingOrder, "TierBoardStyle.boardStackingOrder");
stacking(value.stageStackingOrder, "TierBoardStyle.stageStackingOrder");
stacking(value.itemStackingOrder, "TierBoardStyle.itemStackingOrder");
assert(value.rows.length > 0, "TierBoardStyle.rows is empty.");
const rows = new Set<string>();
for (const [index, row] of value.rows.entries()) {
identity(row.id, `TierBoardStyle.rows.${index}.id`);
assert(!rows.has(row.id), `TierBoardStyle repeats row ${row.id}.`);
rows.add(row.id);
assert(row.label.trim().length > 0, `TierBoardStyle.rows.${index}.label is empty.`);
color(row.color, `TierBoardStyle.rows.${index}.color`);
}
}
export function assertColumnStyle(value: ColumnStyle): void {
assertCommonStyle(value, "ColumnStyle");
assertRankingBoardPaint(value.board, "ColumnStyle.board");
assert(value.rankColors.length > 0, "ColumnStyle.rankColors is empty.");
value.rankColors.forEach((item, index) => color(item, `ColumnStyle.rankColors.${index}`));
for (const [name, numberValue] of Object.entries({
paddingPx: value.paddingPx, rowHeightPx: value.rowHeightPx, rowGapPx: value.rowGapPx, stageSizePx: value.stageSizePx,
})) nonNegative(numberValue, `ColumnStyle.${name}`);
assert(value.rowHeightPx > 0 && value.stageSizePx > 0, "ColumnStyle positive geometry is invalid.");
for (const [name, coordinate] of Object.entries(value.stagePoint)) {
assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `ColumnStyle.stagePoint.${name} is invalid.`);
}
stacking(value.stageStackingOrder, "ColumnStyle.stageStackingOrder");
}
export function assertTopThreeStyle(value: TopThreeStyle): void {
assertCommonStyle(value, "TopThreeStyle");
assert(value.slotColors.length === 3, "TopThreeStyle requires exactly three slot colors.");
value.slotColors.forEach((item, index) => color(item, `TopThreeStyle.slotColors.${index}`));
for (const [name, coordinate] of [["centerX", value.centerX], ["baselineY", value.baselineY]] as const) {
assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `TopThreeStyle.${name} is invalid.`);
}
positive(value.slotGapPx, "TopThreeStyle.slotGapPx");
nonNegative(value.ringWidthPx, "TopThreeStyle.ringWidthPx");
nonNegative(value.labelGapPx, "TopThreeStyle.labelGapPx");
}
export function assertRankingItemSpec(value: RankingItemSpec): void {
identity(value.id, "RankingItemSpec.id");
if (value.variant === "tier-board") {
identity(value.tier, `TierBoardItemSpec.${value.id}.tier`);
assert(typeof value.preset === "boolean", `TierBoardItemSpec.${value.id}.preset is invalid.`);
if (value.preset) assert(!("entry" in value), `Preset TierBoardItemSpec.${value.id} cannot have an entry.`);
else assert(value.entry === "direct" || value.entry === "drop", `TierBoardItemSpec.${value.id}.entry is invalid.`);
} else if (value.variant === "column") {
assert(value.label.trim().length > 0, `ColumnItemSpec.${value.id}.label is empty.`);
integer(value.rank, `ColumnItemSpec.${value.id}.rank`, 1);
assert(typeof value.preset === "boolean", `ColumnItemSpec.${value.id}.preset is invalid.`);
} else {
assert(value.label.trim().length > 0, `TopThreeItemSpec.${value.id}.label is empty.`);
}
if (value.stackingOrder !== undefined) stacking(value.stackingOrder, `RankingItemSpec.${value.id}.stackingOrder`);
}
export function assertRankingTextItemShell(value: RankingTextItemShell): void {
identity(value.id, "RankingTextItemShell.id");
assert(value.variant === "column" || value.variant === "top-three",
"RankingTextItemShell variant is invalid.");
if (value.stackingOrder !== undefined) stacking(value.stackingOrder, `RankingTextItemShell.${value.id}.stackingOrder`);
}
export function sealRankingTextItemShell(value: RankingTextItemShell): RankingTextItemShell {
const result = canonicalize(value) as unknown as RankingTextItemShell;
assertRankingTextItemShell(result);
return result;
}
export function materializeRankingTextItem(shell: RankingTextItemShell, content: Text): RankingItemSpec {
assertRankingTextItemShell(shell);
verifyText(content);
assert(content.value.trim().length > 0, `Ranking Text Item ${shell.id} content is empty.`);
const result: RankingItemSpec = { ...shell, label: content.value };
assertRankingItemSpec(result);
return canonicalize(result) as unknown as RankingItemSpec;
}
export function createRankingItemSpecSet(header: RankingHeader): RankingItemSpecSet {
assertRankingHeader(header);
return { variant: header.variant, items: [] };
}
export function assertRankingItemSpecSet(value: RankingItemSpecSet): void {
assert(["tier-board", "column", "top-three"].includes(value.variant),
"RankingItemSpecSet.variant is invalid.");
const ids = new Set<string>();
const ranks = new Set<number>();
for (const item of value.items) {
assertRankingItemSpec(item);
assert(item.variant === value.variant, "RankingItemSpecSet mixes component variants.");
assert(!ids.has(item.id), `RankingItemSpecSet repeats ${item.id}.`);
ids.add(item.id);
if (item.variant === "column") {
assert(!ranks.has(item.rank), `RankingItemSpecSet repeats Column rank ${item.rank}.`);
ranks.add(item.rank);
}
}
}
export function appendRankingItemSpec(set: RankingItemSpecSet, spec: RankingItemSpec): RankingItemSpecSet {
assertRankingItemSpecSet(set);
assertRankingItemSpec(spec);
assert(spec.variant === set.variant, "Ranking Item variant does not match its component.");
const result: RankingItemSpecSet = { ...set, items: [...set.items, structuredClone(spec)] };
assertRankingItemSpecSet(result);
return canonicalize(result) as unknown as RankingItemSpecSet;
}
export function createTriggeredRankingCandidateSet(): TriggeredRankingCandidateSet {
return { entries: [] };
}
export function assertTriggeredRankingCandidateSet(value: TriggeredRankingCandidateSet): void {
assert(Array.isArray(value.entries), "TriggeredRankingCandidateSet.entries is invalid.");
const itemIds = new Set<string>();
for (const [index, entry] of value.entries.entries()) {
identity(entry.itemId, `TriggeredRankingCandidateSet.entries.${index}.itemId`);
assert(!itemIds.has(entry.itemId), `TriggeredRankingCandidateSet repeats ${entry.itemId}.`);
itemIds.add(entry.itemId);
frame(entry.activation.frame, `TriggeredRankingCandidateSet.entries.${index}.activation.frame`);
assertTemporalInstantFor(entry.activation, { subjectId: entry.itemId });
}
}
export function appendTriggeredRankingCandidate(
set: TriggeredRankingCandidateSet,
spec: RankingItemSpec,
activation: TemporalInstant,
): TriggeredRankingCandidateSet {
assertTriggeredRankingCandidateSet(set);
assertRankingItemSpec(spec);
assert(spec.variant === "top-three", `Ranking Item ${spec.id} consumes a Selection window, not a Moment.`);
assert(!set.entries.some((entry) => entry.itemId === spec.id), `Ranking Item ${spec.id} already has a Moment.`);
const result: TriggeredRankingCandidateSet = {
entries: [...set.entries, { itemId: spec.id, activation: structuredClone(activation) }],
};
assertTriggeredRankingCandidateSet(result);
return canonicalize(result) as unknown as TriggeredRankingCandidateSet;
}
export function buildTriggeredRankingSchedule(input: {
readonly header: RankingHeader;
readonly items: RankingItemSpecSet;
readonly timeline: Timeline;
readonly outer: TemporalWindow;
readonly candidates: TriggeredRankingCandidateSet;
readonly terminal: TemporalInstant;
}): TriggeredRankingSchedule {
assertRankingHeader(input.header);
assertRankingItemSpecSet(input.items);
assert(input.items.variant === input.header.variant, "Ranking schedule variant disagrees with its item set.");
assert(input.header.variant === "top-three", "Only TopThree uses the triggered Ranking schedule.");
assert(input.items.items.length > 0, "Ranking requires at least one Item.");
assertTriggeredRankingCandidateSet(input.candidates);
assertTemporalWindowFor(input.outer, { subjectId: input.header.id, timeline: input.timeline });
assertTemporalInstantFor(input.terminal, { subjectId: input.header.id, timeline: input.timeline });
for (const candidate of input.candidates.entries) {
assertTemporalInstantFor(candidate.activation, { subjectId: candidate.itemId, timeline: input.timeline });
}
const expected = new Set(input.items.items.map((item) => item.id));
const received = new Set(input.candidates.entries.map((entry) => entry.itemId));
assert(expected.size === received.size && [...expected].every((id) => received.has(id)),
"Ranking Items and item-owned Moments differ.");
const ordered = [...input.candidates.entries].sort((left, right) =>
left.activation.frame - right.activation.frame || left.itemId.localeCompare(right.itemId));
const resolved = resolveTriggeredSchedule({
outer: { ...input.outer.span },
terminalFrame: input.terminal.frame,
triggers: ordered.map((item) => ({ id: item.itemId, frame: item.activation.frame })),
});
const entries = ordered.map((candidate, index) => {
const exclusive = resolved.exclusive[index]!;
const cumulative = resolved.cumulative[index]!;
return {
itemId: candidate.itemId,
triggerFrame: exclusive.startFrame,
stage: { ...exclusive },
cumulative: { ...cumulative },
settled: { startFrame: exclusive.endFrameExclusive, endFrameExclusive: resolved.outer.endFrameExclusive },
};
});
const result: TriggeredRankingSchedule = {
id: input.header.id,
variant: input.header.variant,
outer: { ...resolved.outer },
terminalFrame: resolved.terminalFrame,
entries,
};
assertRankingSchedule(result, input.timeline);
return canonicalize(result) as unknown as TriggeredRankingSchedule;
}
function createRankingWindowSet(): RankingWindowSet {
return { entries: [] };
}
function assertRankingWindowSet(value: RankingWindowSet, label: string): void {
assert(Array.isArray(value.entries), `${label}.entries is invalid.`);
const ids = new Set<string>();
for (const [index, entry] of value.entries.entries()) {
identity(entry.itemId, `${label}.entries.${index}.itemId`);
assert(!ids.has(entry.itemId), `${label} repeats ${entry.itemId}.`);
ids.add(entry.itemId);
frame(entry.window.span.startFrame, `${label}.entries.${index}.window.span.startFrame`);
frame(entry.window.span.endFrameExclusive, `${label}.entries.${index}.window.span.endFrameExclusive`);
assert(entry.window.span.endFrameExclusive > entry.window.span.startFrame,
`${label}.entries.${index}.window is empty.`);
assertTemporalWindowFor(entry.window, { subjectId: entry.itemId });
}
}
export const createTierBoardWindowSet = (): TierBoardWindowSet => createRankingWindowSet();
export const createColumnWindowSet = (): ColumnWindowSet => createRankingWindowSet();
export const assertTierBoardWindowSet = (value: TierBoardWindowSet): void => assertRankingWindowSet(value, "TierBoardWindowSet");
export const assertColumnWindowSet = (value: ColumnWindowSet): void => assertRankingWindowSet(value, "ColumnWindowSet");
function appendRankingWindow<T extends TierBoardItemSpec | ColumnItemSpec>(
set: RankingWindowSet,
spec: T,
window: TemporalWindow,
variant: T["variant"],
label: string,
): RankingWindowSet {
assertRankingWindowSet(set, `${label}WindowSet`);
assertRankingItemSpec(spec);
assert(spec.variant === variant, `${label} window requires a ${label} Item.`);
assert(!spec.preset, `Preset ${label} Item ${spec.id} cannot consume a Selection window.`);
assert(!set.entries.some((entry) => entry.itemId === spec.id), `${label} Item ${spec.id} already has a Selection window.`);
assertTemporalWindowFor(window, { subjectId: spec.id });
const result: RankingWindowSet = {
entries: [...set.entries, { itemId: spec.id, window: structuredClone(window) }]
.sort((left, right) => left.itemId.localeCompare(right.itemId)),
};
assertRankingWindowSet(result, `${label}WindowSet`);
return canonicalize(result) as unknown as RankingWindowSet;
}
export function appendTierBoardWindow(
set: TierBoardWindowSet,
spec: TierBoardItemSpec,
window: TemporalWindow,
): TierBoardWindowSet {
return appendRankingWindow(set, spec, window, "tier-board", "TierBoard");
}
export function appendColumnWindow(
set: ColumnWindowSet,
spec: ColumnItemSpec,
window: TemporalWindow,
): ColumnWindowSet {
return appendRankingWindow(set, spec, window, "column", "Column");
}
function buildWindowedRankingSchedule(input: {
readonly header: RankingHeader;
readonly items: RankingItemSpecSet;
readonly timeline: Timeline;
readonly outer: TemporalWindow;
readonly windows: RankingWindowSet;
readonly variant: "tier-board" | "column";
}): TierBoardSchedule | ColumnSchedule {
assertRankingHeader(input.header);
const label = input.variant === "tier-board" ? "TierBoard" : "Column";
assert(input.header.variant === input.variant, `${label} Schedule requires a ${label} header.`);
assertRankingItemSpecSet(input.items);
assert(input.items.variant === input.variant, `${label} Schedule requires ${label} Items.`);
assert(input.items.items.length > 0, `${label} requires at least one Item.`);
assertRankingWindowSet(input.windows, `${label}WindowSet`);
assertTemporalWindowFor(input.outer, { subjectId: input.header.id, timeline: input.timeline });
frame(input.outer.span.startFrame, `${label} outer window start`);
frame(input.outer.span.endFrameExclusive, `${label} outer window end`);
assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, `${label} outer window is empty.`);
const authoredItems = [...input.items.items] as readonly (TierBoardItemSpec | ColumnItemSpec)[];
const expected = new Set(authoredItems.filter((item) => !item.preset).map((item) => item.id));
const received = new Set(input.windows.entries.map((entry) => entry.itemId));
assert(expected.size === received.size && [...expected].every((id) => received.has(id)),
`${label} non-preset Items and Selection windows differ.`);
const orderedWindows = [...input.windows.entries].sort((left, right) =>
left.window.span.startFrame - right.window.span.startFrame
|| left.window.span.endFrameExclusive - right.window.span.endFrameExclusive
|| left.itemId.localeCompare(right.itemId));
for (const entry of orderedWindows) {
assertTemporalWindowFor(entry.window, { subjectId: entry.itemId, timeline: input.timeline });
assert(entry.window.span.startFrame >= input.outer.span.startFrame
&& entry.window.span.endFrameExclusive <= input.outer.span.endFrameExclusive,
`${label} Item ${entry.itemId} window is outside the outer window.`);
if (input.variant === "tier-board") assert(
entry.window.span.endFrameExclusive - entry.window.span.startFrame >= 2,
`TierBoard Item ${entry.itemId} window must span at least two frames so its entrance can be animated.`,
);
}
for (let index = 1; index < orderedWindows.length; index += 1) {
const previous = orderedWindows[index - 1]!;
const current = orderedWindows[index]!;
assert(current.window.span.startFrame >= previous.window.span.endFrameExclusive,
`${label} Item windows ${previous.itemId} and ${current.itemId} overlap.`);
}
const windowOrder = new Map(orderedWindows.map((entry, index) => [entry.itemId, index]));
const authorOrder = new Map(authoredItems.map((item, index) => [item.id, index]));
const items = input.variant === "column"
? [...authoredItems].sort((left, right) => (left as ColumnItemSpec).rank - (right as ColumnItemSpec).rank || left.id.localeCompare(right.id))
: [...authoredItems].sort((left, right) => {
if (left.preset !== right.preset) return left.preset ? -1 : 1;
if (left.preset) return authorOrder.get(left.id)! - authorOrder.get(right.id)!;
return windowOrder.get(left.id)! - windowOrder.get(right.id)!;
});
const result: TierBoardSchedule | ColumnSchedule = {
id: input.header.id,
variant: input.variant,
outer: { ...input.outer.span },
entries: items.map((item) => {
if (item.preset) return {
itemId: item.id,
mode: "preset" as const,
settled: { ...input.outer.span },
};
const window = input.windows.entries.find((entry) => entry.itemId === item.id)!.window.span;
return {
itemId: item.id,
mode: "reveal" as const,
window: { ...window },
settled: { startFrame: window.endFrameExclusive, endFrameExclusive: input.outer.span.endFrameExclusive },
};
}),
};
assertRankingSchedule(result);
return canonicalize(result) as unknown as TierBoardSchedule | ColumnSchedule;
}
export function buildTierBoardSchedule(input: {
readonly header: RankingHeader;
readonly items: RankingItemSpecSet;
readonly timeline: Timeline;
readonly outer: TemporalWindow;
readonly windows: TierBoardWindowSet;
}): TierBoardSchedule {
return buildWindowedRankingSchedule({ ...input, variant: "tier-board" }) as TierBoardSchedule;
}
export function buildColumnSchedule(input: {
readonly header: RankingHeader;
readonly items: RankingItemSpecSet;
readonly timeline: Timeline;
readonly outer: TemporalWindow;
readonly windows: ColumnWindowSet;
}): ColumnSchedule {
return buildWindowedRankingSchedule({ ...input, variant: "column" }) as ColumnSchedule;
}
function assertTriggeredRankingSchedule(value: TriggeredRankingSchedule): void {
identity(value.id, "RankingSchedule.id");
assert(value.variant === "top-three", "Triggered RankingSchedule.variant is invalid.");
frame(value.outer.startFrame, "RankingSchedule.outer.startFrame");
frame(value.outer.endFrameExclusive, "RankingSchedule.outer.endFrameExclusive");
assert(value.outer.endFrameExclusive > value.outer.startFrame, "RankingSchedule.outer is empty.");
frame(value.terminalFrame, "RankingSchedule.terminalFrame");
assert(value.terminalFrame <= value.outer.endFrameExclusive, "RankingSchedule terminal exceeds outer end.");
assert(value.entries.length > 0, "RankingSchedule.entries is empty.");
const ids = new Set<string>();
let previous = value.outer.startFrame - 1;
for (const [index, entry] of value.entries.entries()) {
identity(entry.itemId, `RankingSchedule.entries.${index}.itemId`);
assert(!ids.has(entry.itemId), `RankingSchedule repeats ${entry.itemId}.`);
ids.add(entry.itemId);
frame(entry.triggerFrame, `RankingSchedule.entries.${index}.triggerFrame`);
assert(entry.triggerFrame > previous, "RankingSchedule trigger frames are not strictly increasing.");
previous = entry.triggerFrame;
assert(entry.stage.startFrame === entry.triggerFrame
&& entry.stage.endFrameExclusive === (value.entries[index + 1]?.triggerFrame ?? value.terminalFrame),
`RankingSchedule.entries.${index}.stage is inconsistent.`);
assert(entry.cumulative.startFrame === entry.triggerFrame
&& entry.cumulative.endFrameExclusive === value.outer.endFrameExclusive,
`RankingSchedule.entries.${index}.cumulative is inconsistent.`);
assert(entry.settled.startFrame === entry.stage.endFrameExclusive
&& entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
`RankingSchedule.entries.${index}.settled is inconsistent.`);
}
assert(value.entries[0]!.triggerFrame >= value.outer.startFrame, "RankingSchedule starts before its outer window.");
assert(value.entries.at(-1)!.stage.endFrameExclusive === value.terminalFrame,
"RankingSchedule final stage does not end at terminal.");
}
function assertWindowedRankingSchedule(value: TierBoardSchedule | ColumnSchedule): void {
const label = value.variant === "tier-board" ? "TierBoardSchedule" : "ColumnSchedule";
identity(value.id, `${label}.id`);
frame(value.outer.startFrame, `${label}.outer.startFrame`);
frame(value.outer.endFrameExclusive, `${label}.outer.endFrameExclusive`);
assert(value.outer.endFrameExclusive > value.outer.startFrame, `${label}.outer is empty.`);
assert(value.entries.length > 0, `${label}.entries is empty.`);
const ids = new Set<string>();
const windows: Array<{ readonly itemId: string; readonly startFrame: number; readonly endFrameExclusive: number }> = [];
let tierRevealStarted = false;
for (const [index, entry] of value.entries.entries()) {
identity(entry.itemId, `${label}.entries.${index}.itemId`);
assert(!ids.has(entry.itemId), `${label} repeats ${entry.itemId}.`);
ids.add(entry.itemId);
if (entry.mode === "preset") {
assert(value.variant !== "tier-board" || !tierRevealStarted,
`TierBoardSchedule preset ${entry.itemId} appears after a reveal Item.`);
assert(entry.settled.startFrame === value.outer.startFrame
&& entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
`${label} preset ${entry.itemId} does not occupy the outer window.`);
continue;
}
tierRevealStarted = true;
frame(entry.window.startFrame, `${label}.entries.${index}.window.startFrame`);
frame(entry.window.endFrameExclusive, `${label}.entries.${index}.window.endFrameExclusive`);
assert(entry.window.startFrame >= value.outer.startFrame
&& entry.window.endFrameExclusive <= value.outer.endFrameExclusive
&& entry.window.endFrameExclusive > entry.window.startFrame,
`${label}.entries.${index}.window is outside the outer window.`);
assert(entry.settled.startFrame === entry.window.endFrameExclusive
&& entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
`${label}.entries.${index}.settled is inconsistent.`);
windows.push({ itemId: entry.itemId, ...entry.window });
}
windows.sort((left, right) => left.startFrame - right.startFrame
|| left.endFrameExclusive - right.endFrameExclusive || left.itemId.localeCompare(right.itemId));
for (let index = 1; index < windows.length; index += 1) {
assert(windows[index]!.startFrame >= windows[index - 1]!.endFrameExclusive,
`${label} windows ${windows[index - 1]!.itemId} and ${windows[index]!.itemId} overlap.`);
}
if (value.variant === "tier-board") {
const revealOrder = value.entries.filter((entry) => entry.mode === "reveal");
for (let index = 1; index < revealOrder.length; index += 1) {
const previous = revealOrder[index - 1]!;
const current = revealOrder[index]!;
assert(previous.mode === "reveal" && current.mode === "reveal"
&& current.window.startFrame >= previous.window.endFrameExclusive,
`TierBoardSchedule reveal order is not chronological at ${current.itemId}.`);
}
}
}
export function assertRankingSchedule(value: RankingSchedule, timeline?: Timeline): void {
if (value.variant === "top-three") assertTriggeredRankingSchedule(value);
else assertWindowedRankingSchedule(value);
if (timeline !== undefined) {
assertTimelineIdentity(timeline);
assert(value.outer.endFrameExclusive <= timelineFrameCount(timeline), "RankingSchedule exceeds Timeline.");
}
}
function emptySet<T extends { readonly items: readonly unknown[] }>(): T {
return { items: [] } as unknown as T;
}
export const createTierBoardItemSet = (): TierBoardItemSet => emptySet();
export const createColumnItemSet = (): ColumnItemSet => emptySet();
export const createTopThreeItemSet = (): TopThreeItemSet => emptySet();
function ensureNew(items: readonly { readonly id: string }[], id: string): void {
assert(!items.some((item) => item.id === id), `Ranking Item ${id} is duplicated.`);
}
export function appendTierBoardItem(set: TierBoardItemSet, spec: TierBoardItemSpec, icon: TierBoardItem["icon"]): TierBoardItemSet {
assert(Array.isArray(set.items), "TierBoardItemSet is invalid.");
assertRankingItemSpec(spec);
assertBlobImage(icon, `TierBoardItem.${spec.id}.icon`);
ensureNew(set.items, spec.id);
return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), icon: structuredClone(icon) }] }) as unknown as TierBoardItemSet;
}
export function appendColumnItem(set: ColumnItemSet, spec: ColumnItemSpec, icon?: ColumnItem["icon"]): ColumnItemSet {
assert(Array.isArray(set.items), "ColumnItemSet is invalid.");
assertRankingItemSpec(spec);
if (icon !== undefined) assertBlobImage(icon, `ColumnItem.${spec.id}.icon`);
ensureNew(set.items, spec.id);
return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), ...(icon === undefined ? {} : { icon: structuredClone(icon) }) }] }) as unknown as ColumnItemSet;
}
export function appendTopThreeItem(set: TopThreeItemSet, spec: TopThreeItemSpec, icon?: TopThreeItem["icon"]): TopThreeItemSet {
assert(Array.isArray(set.items), "TopThreeItemSet is invalid.");
assertRankingItemSpec(spec);
if (icon !== undefined) assertBlobImage(icon, `TopThreeItem.${spec.id}.icon`);
ensureNew(set.items, spec.id);
return canonicalize({ ...set, items: [...set.items, { ...structuredClone(spec), ...(icon === undefined ? {} : { icon: structuredClone(icon) }) }] }) as unknown as TopThreeItemSet;
}
function idsEqual(schedule: TriggeredRankingSchedule, items: readonly { readonly id: string }[]): void {
assert(schedule.entries.length === items.length, "Ranking Program item count differs from its Schedule.");
for (const [index, item] of items.entries()) {
assert(schedule.entries[index]?.itemId === item.id, "Ranking Program item order differs from its Schedule.");
}
}
function orderForSchedule<T extends { readonly id: string }>(
schedule: TriggeredRankingSchedule,
items: readonly T[],
): T[] {
const byId = new Map(items.map((item) => [item.id, item]));
assert(byId.size === items.length && schedule.entries.length === items.length,
"Ranking Program item count differs from its Schedule.");
return schedule.entries.map((entry) => {
const item = byId.get(entry.itemId);
assert(item !== undefined, `Ranking Schedule references unknown Item ${entry.itemId}.`);
return item;
});
}
function windowedIdsEqual(schedule: TierBoardSchedule | ColumnSchedule, items: readonly { readonly id: string }[]): void {
assert(schedule.entries.length === items.length, "Windowed Ranking Program item count differs from its Schedule.");
const scheduled = new Set(schedule.entries.map((entry) => entry.itemId));
assert(scheduled.size === items.length && items.every((item) => scheduled.has(item.id)),
"Windowed Ranking Program Items differ from its Schedule.");
}
export function fitRankingEntranceMotion(
durationFrames: number,
preferredAppearFrames: number,
preferredMoveFrames: number,
needsMove: boolean,
): { readonly appearFrames: number; readonly moveFrames: number } {
assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Ranking entrance duration is invalid.");
if (!needsMove) return { appearFrames: Math.min(preferredAppearFrames, durationFrames), moveFrames: 0 };
const moveFrames = Math.min(preferredMoveFrames, Math.max(1, durationFrames - 1));
return { appearFrames: Math.min(preferredAppearFrames, durationFrames - moveFrames), moveFrames };
}
export function resolveTierBoardMotion(
durationFrames: number,
appearFrames: number,
moveFrames: number,
): { readonly appearEndFrame: number; readonly moveStartFrame: number; readonly moveEndFrame?: number } {
assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "TierBoard Item duration is invalid.");
assert(Number.isSafeInteger(appearFrames) && appearFrames > 0, "TierBoard appear duration is invalid.");
assert(Number.isSafeInteger(moveFrames) && moveFrames > 0, "TierBoard move duration is invalid.");
const moveStartFrame = Math.max(appearFrames, durationFrames - moveFrames);
return {
appearEndFrame: appearFrames,
moveStartFrame,
...(durationFrames > moveStartFrame ? { moveEndFrame: durationFrames } : {}),
};
}
export function fitColumnRevealMotion(
durationFrames: number,
preferredAppearFrames: number,
preferredMoveFrames: number,
): { readonly mode: "direct" } | { readonly mode: "stage"; readonly appearFrames: number; readonly moveFrames: number } {
assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Column reveal duration is invalid.");
assert(Number.isSafeInteger(preferredAppearFrames) && preferredAppearFrames > 0, "Column appear duration is invalid.");
assert(Number.isSafeInteger(preferredMoveFrames) && preferredMoveFrames > 0, "Column move duration is invalid.");
if (durationFrames === 1) return { mode: "direct" };
const preferredTotal = preferredAppearFrames + preferredMoveFrames;
if (durationFrames >= preferredTotal) {
return { mode: "stage", appearFrames: preferredAppearFrames, moveFrames: preferredMoveFrames };
}
const appearFrames = Math.min(durationFrames - 1,
Math.max(1, Math.round(durationFrames * preferredAppearFrames / preferredTotal)));
return { mode: "stage", appearFrames, moveFrames: durationFrames - appearFrames };
}
export function buildTierBoardProgram(header: RankingHeader, withinValue: SpatialFrame, frameValue: SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {
assert(header.variant === "tier-board" && schedule.variant === "tier-board", "TierBoard variant is inconsistent.");
assertSpatialFrame(withinValue);
assertSpatialFrame(frameValue);
assertTierBoardStyle(style);
windowedIdsEqual(schedule, set.items);
const byId = new Map(set.items.map((item) => [item.id, item]));
const items = schedule.entries.map((entry) => structuredClone(byId.get(entry.itemId)!));
const rows = new Set(style.rows.map((row) => row.id));
for (const item of items) assert(rows.has(item.tier), `TierBoard Item ${item.id} references unknown tier ${item.tier}.`);
const result: TierBoardProgram = { id: header.id, within: structuredClone(withinValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
assertTierBoardProgram(result);
return canonicalize(result) as unknown as TierBoardProgram;
}
export function buildColumnProgram(header: RankingHeader, withinValue: SpatialFrame, frameValue: SpatialFrame, schedule: RankingSchedule, style: ColumnStyle, set: ColumnItemSet): ColumnProgram {
assert(header.variant === "column" && schedule.variant === "column", "Column variant is inconsistent.");
assertSpatialFrame(withinValue);
assertSpatialFrame(frameValue);
assertColumnStyle(style);
windowedIdsEqual(schedule, set.items);
const items = [...set.items].map((item) => structuredClone(item)).sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
const result: ColumnProgram = { id: header.id, within: structuredClone(withinValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
assertColumnProgram(result);
return canonicalize(result) as unknown as ColumnProgram;
}
export function buildTopThreeProgram(header: RankingHeader, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: TopThreeStyle, set: TopThreeItemSet): TopThreeProgram {
assert(header.variant === "top-three" && schedule.variant === "top-three", "TopThree variant is inconsistent.");
assertSpatialFrame(frameValue);
assertTopThreeStyle(style);
assert(set.items.length <= 3, "TopThree accepts at most three Items.");
const items = orderForSchedule(schedule, set.items).map((item) => structuredClone(item));
const result: TopThreeProgram = { id: header.id, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
assertTopThreeProgram(result);
return canonicalize(result) as unknown as TopThreeProgram;
}
export function assertTierBoardProgram(value: TierBoardProgram): void {
assertRankingSchedule(value.schedule);
assert(value.schedule.variant === "tier-board", "TierBoardProgram Schedule variant is invalid.");
assertSpatialFrame(value.within);
assertSpatialFrame(value.frame);
assertTierBoardStyle(value.style);
windowedIdsEqual(value.schedule, value.items);
value.items.forEach((item) => { assertRankingItemSpec(item); assertBlobImage(item.icon, `TierBoardItem.${item.id}.icon`); });
}
export function assertColumnProgram(value: ColumnProgram): void {
assertRankingSchedule(value.schedule);
assert(value.schedule.variant === "column", "ColumnProgram Schedule variant is invalid.");
assertSpatialFrame(value.within);
assertSpatialFrame(value.frame);
assertColumnStyle(value.style);
windowedIdsEqual(value.schedule, value.items);
value.items.forEach((item) => { assertRankingItemSpec(item); if (item.icon !== undefined) assertBlobImage(item.icon, `ColumnItem.${item.id}.icon`); });
for (let index = 1; index < value.items.length; index += 1) {
assert(value.items[index - 1]!.rank < value.items[index]!.rank, "ColumnProgram Items are not ordered by unique rank.");
}
}
export function assertTopThreeProgram(value: TopThreeProgram): void {
assertRankingSchedule(value.schedule);
assert(value.schedule.variant === "top-three", "TopThreeProgram Schedule variant is invalid.");
assertSpatialFrame(value.frame);
assertTopThreeStyle(value.style);
assert(value.items.length <= 3, "TopThreeProgram exceeds three Items.");
idsEqual(value.schedule, value.items);
value.items.forEach((item) => { assertRankingItemSpec(item); if (item.icon !== undefined) assertBlobImage(item.icon, `TopThreeItem.${item.id}.icon`); });
}
function event(id: string, itemId: string, kind: "appear" | "move", eventFrame: number): RankingSoundEvent {
return { id: `${id}:${itemId}:${kind}`, itemId, kind, frame: eventFrame };
}
function sealEvents(id: string, variant: RankingVariant, events: readonly RankingSoundEvent[]): RankingSoundEventPlan {
const value: RankingSoundEventPlan = { id, variant, events };
assertRankingSoundEventPlan(value);
return canonicalize(value) as unknown as RankingSoundEventPlan;
}
export function buildTierBoardSoundEvents(schedule: RankingSchedule, style: TierBoardStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
assert(schedule.variant === "tier-board" && specs.variant === "tier-board", "TierBoard event inputs disagree.");
assertTierBoardStyle(style);
windowedIdsEqual(schedule, specs.items);
const byId = new Map(specs.items.map((spec) => [spec.id, spec as TierBoardItemSpec]));
const events = schedule.entries.flatMap((entry) => {
if (entry.mode === "preset") return [];
const spec = byId.get(entry.itemId)!;
assert(!spec.preset, `TierBoard reveal ${entry.itemId} cannot be preset.`);
const duration = entry.window.endFrameExclusive - entry.window.startFrame;
const phases = resolveTierBoardMotion(duration, style.motion.appearFrames, style.motion.moveFrames);
return [event(schedule.id, entry.itemId, "appear", entry.window.startFrame),
...(spec.entry === "drop" && phases.moveEndFrame !== undefined
? [event(schedule.id, entry.itemId, "move", entry.window.startFrame + phases.moveStartFrame)]
: [])];
}).sort((left, right) => left.frame - right.frame || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id));
return sealEvents(schedule.id, schedule.variant, events);
}
export function buildColumnSoundEvents(schedule: RankingSchedule, style: ColumnStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
assert(schedule.variant === "column" && specs.variant === "column", "Column event inputs disagree.");
assertColumnStyle(style);
windowedIdsEqual(schedule, specs.items);
const events = schedule.entries.flatMap((entry) => {
if (entry.mode === "preset") return [];
const duration = entry.window.endFrameExclusive - entry.window.startFrame;
const fitted = fitColumnRevealMotion(duration, style.motion.appearFrames, style.motion.moveFrames);
return [event(schedule.id, entry.itemId, "appear", entry.window.startFrame),
...(fitted.mode === "direct" ? []
: [event(schedule.id, entry.itemId, "move", entry.window.endFrameExclusive - fitted.moveFrames)])];
}).sort((left, right) => left.frame - right.frame || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id));
return sealEvents(schedule.id, schedule.variant, events);
}
export function buildTopThreeSoundEvents(schedule: RankingSchedule, style: TopThreeStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {
assert(schedule.variant === "top-three" && specs.variant === "top-three", "TopThree event inputs disagree.");
assertTopThreeStyle(style);
orderForSchedule(schedule, specs.items);
return sealEvents(schedule.id, schedule.variant,
schedule.entries.map((entry) => event(schedule.id, entry.itemId, "appear", entry.triggerFrame)));
}
export function assertRankingSoundEventPlan(value: RankingSoundEventPlan): void {
identity(value.id, "RankingSoundEventPlan.id");
assert(["tier-board", "column", "top-three"].includes(value.variant),
"RankingSoundEventPlan.variant is invalid.");
const ids = new Set<string>();
for (const item of value.events) {
identity(item.id, "RankingSoundEvent.id");
identity(item.itemId, "RankingSoundEvent.itemId");
assert(item.kind === "appear" || item.kind === "move", `RankingSoundEvent ${item.id} kind is invalid.`);
frame(item.frame, `RankingSoundEvent ${item.id}.frame`);
assert(!ids.has(item.id), `RankingSoundEventPlan repeats ${item.id}.`);
ids.add(item.id);
}
}
export function createRankingSoundSet(): RankingSoundSet {
return {};
}
export function appendRankingSound(set: RankingSoundSet, kind: "appear" | "move", media: SynchronizedMedia): RankingSoundSet {
verifySynchronizedMedia(media);
assert(media.audio !== undefined, `Ranking ${kind} sound has no normalized audio.`);
assert(set[kind] === undefined, `Ranking ${kind} sound is already set.`);
return canonicalize({ ...set, [kind]: structuredClone(media) }) as unknown as RankingSoundSet;
}