Skip to content

Write HTML. Render video. Built for agents.

7.6 KB
Raw Blame
// packages/core/src/slideshow/parseSlideshow.ts
import type {
  SlideshowManifest,
  SlideRef,
  SlideHotspot,
  ResolvedSlide,
  ResolvedSlideshow,
  ResolvedSlideSequence,
} from "./slideshow.types";

export const SLIDESHOW_ISLAND_TYPE = "application/hyperframes-slideshow+json";

/**
 * Builds the island <script> matcher. Capture group 1 = inner JSON.
 *
 * Factory (fresh RegExp per call) on purpose: a RegExp with the `g` flag carries
 * a mutable `lastIndex`, so callers that need `g` must call this each time rather
 * than caching a shared instance.
 */
export function slideshowIslandRegex(flags = "i"): RegExp {
  // Escape ALL regex metacharacters in the constant (CodeQL flags the incomplete
  // `\` escape). The constant has none today, but a complete escape is correct.
  const escaped = SLIDESHOW_ISLAND_TYPE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  return new RegExp(`<script[^>]*type=["']${escaped}["'][^>]*>([\\s\\S]*?)<\\/script>`, flags);
}

interface SceneRange {
  id: string;
  start: number;
  duration: number;
}

/** Extract the JSON island from composition HTML. Returns null if absent. */
export function parseSlideshowManifest(html: string): SlideshowManifest | null {
  // Match <script type="application/hyperframes-slideshow+json"> ... </script>
  const re = slideshowIslandRegex("i");
  const match = re.exec(html);
  if (!match || match[1] === undefined) return null;
  const raw = match[1].trim();
  if (raw.length === 0) return null;
  const parsed: unknown = JSON.parse(raw);
  if (!isManifest(parsed)) {
    throw new Error("slideshow island is not a valid SlideshowManifest");
  }
  return parsed;
}

function isOptionalNumberArray(v: unknown): boolean {
  return v === undefined || (Array.isArray(v) && v.every((n) => typeof n === "number"));
}

function isOptionalBoolean(v: unknown): v is boolean | undefined {
  return v === undefined || typeof v === "boolean";
}

function isRecord(v: unknown): v is Record<string, unknown> {
  return typeof v === "object" && v !== null && !Array.isArray(v);
}

function isHotspotRegion(v: unknown): boolean {
  return (
    isRecord(v) &&
    [v["x"], v["y"], v["w"], v["h"]].every(
      (coordinate) => typeof coordinate === "number" && Number.isFinite(coordinate),
    )
  );
}

function isSlideHotspot(v: unknown): v is SlideHotspot {
  return (
    isRecord(v) &&
    typeof v["id"] === "string" &&
    typeof v["label"] === "string" &&
    typeof v["target"] === "string" &&
    (v["region"] === undefined || isHotspotRegion(v["region"]))
  );
}

function isSlideRef(v: unknown): v is SlideRef {
  if (!isRecord(v)) return false;
  const r = v;
  if (typeof r["sceneId"] !== "string") return false;
  if (!isOptionalNumberArray(r["fragments"])) return false;
  if (
    r["hotspots"] !== undefined &&
    (!Array.isArray(r["hotspots"]) || !r["hotspots"].every(isSlideHotspot))
  )
    return false;
  if (!isOptionalBoolean(r["autoplay"])) return false;
  return true;
}

function isSlideSequence(v: unknown): boolean {
  if (typeof v !== "object" || v === null) return false;
  const s = v as Record<string, unknown>;
  return (
    typeof s["id"] === "string" &&
    typeof s["label"] === "string" &&
    Array.isArray(s["slides"]) &&
    s["slides"].every(isSlideRef)
  );
}

function isManifest(v: unknown): v is SlideshowManifest {
  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
  const o = v as Record<string, unknown>;
  if (!Array.isArray(o["slides"]) || !o["slides"].every(isSlideRef)) return false;
  if (o["slideSequences"] !== undefined) {
    if (!Array.isArray(o["slideSequences"]) || !o["slideSequences"].every(isSlideSequence))
      return false;
  }
  return true;
}

function missingBoundError(sceneId: string, missing: "startTime" | "endTime"): string {
  const present = missing === "startTime" ? "endTime" : "startTime";
  return `slide "${sceneId}" sets ${present} but ${missing} cannot be resolved (no scene "${sceneId}")`;
}

// fallow-ignore-next-line complexity
function resolveTimeRange(
  ref: SlideRef,
  scene: SceneRange | undefined,
  errors: string[],
): { start: number; end: number } {
  const { startTime, endTime, sceneId } = ref;

  // Both explicit — use them directly, no scene needed.
  if (startTime !== undefined && endTime !== undefined) {
    return { start: startTime, end: endTime };
  }

  // Neither explicit — resolve both from scene.
  if (startTime === undefined && endTime === undefined) {
    if (!scene) {
      errors.push(`slide references unresolved sceneId "${sceneId}"`);
      return { start: 0, end: 0 };
    }
    return { start: scene.start, end: scene.start + scene.duration };
  }

  // Exactly one bound explicit — fill from scene, or report a clear error.
  if (!scene) {
    const missing = startTime === undefined ? "startTime" : "endTime";
    errors.push(missingBoundError(sceneId, missing));
    const bound = startTime ?? endTime ?? 0;
    return { start: bound, end: bound };
  }

  return {
    start: startTime ?? scene.start,
    end: endTime ?? scene.start + scene.duration,
  };
}

function validateFragments(
  sceneId: string,
  fragments: number[],
  start: number,
  end: number,
  errors: string[],
): void {
  for (const f of fragments) {
    if (f < start || f > end) {
      errors.push(`slide "${sceneId}" fragment ${f} is outside range [${start}, ${end}]`);
    }
  }
}

function resolveSlide(
  ref: SlideRef,
  sceneById: Map<string, SceneRange>,
  errors: string[],
): ResolvedSlide {
  const scene = sceneById.get(ref.sceneId);
  const { start, end } = resolveTimeRange(ref, scene, errors);
  if (ref.startTime !== undefined && ref.endTime !== undefined && end <= start) {
    errors.push(`slide "${ref.sceneId}" has endTime (${end}) <= startTime (${start})`);
  }
  const fragments = [...new Set(ref.fragments ?? [])].sort((a, b) => a - b);
  validateFragments(ref.sceneId, fragments, start, end, errors);
  return { ...ref, start, end, fragments, hotspots: ref.hotspots ?? [] };
}

export function resolveSlideshow(
  manifest: SlideshowManifest,
  scenes: SceneRange[],
): { resolved: ResolvedSlideshow; errors: string[] } {
  const errors: string[] = [];
  const sceneById = new Map(scenes.map((s) => [s.id, s]));

  const sequences: Record<string, ResolvedSlideSequence> = {};
  for (const seq of manifest.slideSequences ?? []) {
    // Flag duplicate sequence ids rather than silently overwriting the earlier one.
    if (Object.prototype.hasOwnProperty.call(sequences, seq.id)) {
      errors.push(`duplicate slideSequence id "${seq.id}": only the last definition is kept`);
    }
    sequences[seq.id] = {
      id: seq.id,
      label: seq.label,
      slides: seq.slides.map((s) => resolveSlide(s, sceneById, errors)),
    };
  }

  const slides = manifest.slides.map((s) => resolveSlide(s, sceneById, errors));

  // Validate hotspot targets.
  const allSlides = [...slides, ...Object.values(sequences).flatMap((s) => s.slides)];
  for (const slide of allSlides) {
    for (const h of slide.hotspots) {
      const seq = sequences[h.target];
      if (!seq) {
        errors.push(`hotspot "${h.id}" targets unknown sequence "${h.target}"`);
      } else if (seq.slides.length === 0) {
        errors.push(`hotspot "${h.id}" targets empty sequence "${h.target}"`);
      }
    }
  }

  // Validate no main-line overlap (sorted by start; adjacent compare).
  const ordered = [...slides].sort((a, b) => a.start - b.start);
  for (let i = 1; i < ordered.length; i++) {
    const prev = ordered[i - 1];
    const curr = ordered[i];
    if (prev !== undefined && curr !== undefined && curr.start < prev.end) {
      errors.push(`main-line slides "${prev.sceneId}" and "${curr.sceneId}" overlap`);
    }
  }

  return { resolved: { slides, sequences }, errors };
}