Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

44.5 KB
Raw Blame
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;
}