@hyperframes/studio 0.2.0 → 0.2.2-alpha.1

package/src/captions/generator.test.ts

@@ -0,0 +1,279 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest";
+import { generateCaptionHtml } from "./generator.js";
+import { buildCaptionModel, TranscriptWord } from "./parser.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const SAMPLE_TRANSCRIPT: TranscriptWord[] = [
+  { text: "We", start: 0.1, end: 0.3 },
+  { text: "asked", start: 0.4, end: 0.6 },
+  { text: "what", start: 0.7, end: 0.9 },
+  { text: "you", start: 1.0, end: 1.2 },
+  { text: "needed.", start: 1.3, end: 1.8 },
+  { text: "Forty-seven", start: 1.9, end: 2.3 },
+  { text: "percent", start: 2.4, end: 2.7 },
+];
+
+function buildTestModel(wordsPerGroup = 5) {
+  return buildCaptionModel(SAMPLE_TRANSCRIPT, {
+    width: 1920,
+    height: 1080,
+    duration: 16,
+    wordsPerGroup,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("generateCaptionHtml", () => {
+  describe("HTML structure", () => {
+    it("wraps output in a <template id='captions-template'>", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('<template id="captions-template">');
+      expect(html).toContain("</template>");
+    });
+
+    it("includes correct data-composition-id, data-width, data-height, data-duration attributes", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('data-composition-id="captions"');
+      expect(html).toContain('data-width="1920"');
+      expect(html).toContain('data-height="1080"');
+      expect(html).toContain('data-duration="16"');
+    });
+
+    it("includes the captions-container div", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('<div id="captions-container"></div>');
+    });
+
+    it("includes a <style> block", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("<style>");
+      expect(html).toContain("</style>");
+    });
+
+    it("includes a <script> block", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("<script>");
+      expect(html).toContain("</script>");
+    });
+  });
+
+  describe("CSS generation", () => {
+    it("includes composition base styles with correct dimensions", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('data-composition-id="captions"');
+      expect(html).toContain("width: 1920px");
+      expect(html).toContain("height: 1080px");
+    });
+
+    it("includes .caption-group base styles with opacity: 0", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain(".caption-group");
+      expect(html).toContain("opacity: 0");
+    });
+
+    it("includes .word base styles with display: inline-block", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain(".word");
+      expect(html).toContain("display: inline-block");
+    });
+
+    it("includes per-group CSS class with font styles from DEFAULT_STYLE", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      // DEFAULT_STYLE has fontFamily: "sans-serif" and fontSize: 48
+      expect(html).toContain("font-family: sans-serif");
+      expect(html).toContain("font-size: 48px");
+    });
+
+    it("includes per-group CSS class for each group", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      // Two groups: group-0 and group-1
+      expect(html).toContain("group-0");
+      expect(html).toContain("group-1");
+    });
+  });
+
+  describe("TRANSCRIPT array", () => {
+    it("includes a TRANSCRIPT array in the script block", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("const TRANSCRIPT =");
+    });
+
+    it("includes all word texts from the transcript", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('"We"');
+      expect(html).toContain('"asked"');
+      expect(html).toContain('"what"');
+      expect(html).toContain('"you"');
+      expect(html).toContain('"needed."');
+      expect(html).toContain('"Forty-seven"');
+      expect(html).toContain('"percent"');
+    });
+
+    it("includes start and end timing for words", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('"start": 0.1');
+      expect(html).toContain('"end": 0.3');
+      expect(html).toContain('"start": 1.9');
+      expect(html).toContain('"end": 2.7');
+    });
+
+    it("TRANSCRIPT contains all 7 words from the sample", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      // Count occurrences of "start" property in the TRANSCRIPT JSON
+      const transcriptSection = html.slice(
+        html.indexOf("const TRANSCRIPT ="),
+        html.indexOf("const TRANSCRIPT =") + 1000,
+      );
+      const startCount = (transcriptSection.match(/"start":/g) ?? []).length;
+      expect(startCount).toBe(7);
+    });
+  });
+
+  describe("GSAP timeline", () => {
+    it("registers the timeline via window.__timelines", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('window.__timelines["captions"]');
+    });
+
+    it("creates a gsap.timeline() call", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("gsap.timeline(");
+    });
+
+    it("includes entrance tween with opacity: 1 for each group", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("opacity: 1");
+    });
+
+    it("includes exit tween with opacity: 0 for each group", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("opacity: 0");
+    });
+
+    it("uses group start time as position for entrance tween", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      // First group starts at 0.1 (first word start)
+      expect(html).toContain(", 0.1)");
+    });
+
+    it("creates caption-group div elements with class='clip'", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("caption-group clip");
+    });
+
+    it("creates word span elements with class='word clip'", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("word clip");
+    });
+
+    it("sets data-start and data-end on group elements", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("dataset.start");
+      expect(html).toContain("dataset.end");
+    });
+
+    it("wraps everything in an IIFE", () => {
+      const model = buildTestModel();
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("(function ()");
+      expect(html).toContain("})();");
+    });
+  });
+
+  describe("positioning", () => {
+    it("centers groups without explicit x/y using transform: translateX(-50%)", () => {
+      const model = buildTestModel();
+      // DEFAULT_STYLE has x: 0 and y: 0
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("translateX(-50%)");
+    });
+
+    it("uses absolute left/top when group style has explicit x/y", () => {
+      const model = buildTestModel();
+      // Override the first group's style to have explicit position
+      const firstGroupId = model.groupOrder[0];
+      const firstGroup = model.groups.get(firstGroupId);
+      if (firstGroup) {
+        firstGroup.style = { ...firstGroup.style, x: 200, y: 300 };
+      }
+      const html = generateCaptionHtml(model);
+      expect(html).toContain("200px");
+      expect(html).toContain("300px");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles an empty model (no segments or groups) without throwing", () => {
+      const model = buildCaptionModel([], {
+        width: 1280,
+        height: 720,
+        duration: 5,
+      });
+      expect(() => generateCaptionHtml(model)).not.toThrow();
+    });
+
+    it("empty model still produces valid template wrapper", () => {
+      const model = buildCaptionModel([], {
+        width: 1280,
+        height: 720,
+        duration: 5,
+      });
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('<template id="captions-template">');
+      expect(html).toContain('data-composition-id="captions"');
+    });
+
+    it("handles custom dimensions correctly", () => {
+      const model = buildCaptionModel(SAMPLE_TRANSCRIPT, {
+        width: 1280,
+        height: 720,
+        duration: 30,
+      });
+      const html = generateCaptionHtml(model);
+      expect(html).toContain('data-width="1280"');
+      expect(html).toContain('data-height="720"');
+      expect(html).toContain('data-duration="30"');
+      expect(html).toContain("width: 1280px");
+      expect(html).toContain("height: 720px");
+    });
+
+    it("words with special characters are escaped in JS output", () => {
+      const transcript: TranscriptWord[] = [{ text: "it's", start: 0.0, end: 0.5 }];
+      const model = buildCaptionModel(transcript, {
+        width: 1920,
+        height: 1080,
+        duration: 5,
+      });
+      expect(() => generateCaptionHtml(model)).not.toThrow();
+    });
+  });
+});

package/src/captions/generator.ts

@@ -0,0 +1,376 @@
+// Caption HTML Generator
+// Serializes a CaptionModel into a complete captions.html HyperFrames composition.
+
+import type {
+  CaptionModel,
+  CaptionSegment,
+  CaptionStyle,
+  CaptionContainerStyle,
+  CaptionShadow,
+  CaptionGlow,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Serializes a CaptionModel into a complete captions.html composition string.
+ *
+ * Output format:
+ * ```html
+ * <template id="captions-template">
+ *   <div data-composition-id="captions" data-width="..." data-height="..." data-duration="...">
+ *     <div id="captions-container"></div>
+ *     <style>/* generated CSS *\/</style>
+ *     <script>/* generated JS *\/</script>
+ *   </div>
+ * </template>
+ * ```
+ */
+export function generateCaptionHtml(model: CaptionModel): string {
+  const css = generateCss(model);
+  const js = generateJs(model);
+
+  const durationStr = model.duration.toString();
+
+  return [
+    `<template id="captions-template">`,
+    `  <div data-composition-id="captions" data-width="${model.width}" data-height="${model.height}" data-duration="${durationStr}">`,
+    `    <div id="captions-container"></div>`,
+    `    <style>`,
+    indent(css, 6),
+    `    </style>`,
+    `    <script>`,
+    indent(js, 6),
+    `    </script>`,
+    `  </div>`,
+    `</template>`,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CSS generation
+// ---------------------------------------------------------------------------
+
+function generateCss(model: CaptionModel): string {
+  const lines: string[] = [];
+
+  // Base composition styles
+  lines.push(
+    `[data-composition-id="captions"] {`,
+    `  position: relative;`,
+    `  width: ${model.width}px;`,
+    `  height: ${model.height}px;`,
+    `  background: transparent;`,
+    `  overflow: hidden;`,
+    `}`,
+    ``,
+  );
+
+  // Container styles
+  lines.push(`#captions-container {`, `  position: absolute;`, `  inset: 0;`, `}`, ``);
+
+  // .caption-group base styles
+  lines.push(
+    `.caption-group {`,
+    `  position: absolute;`,
+    `  display: flex;`,
+    `  flex-wrap: wrap;`,
+    `  gap: 0.25em;`,
+    `  opacity: 0;`,
+    `}`,
+    ``,
+  );
+
+  // .word base styles
+  lines.push(`.word {`, `  display: inline-block;`, `}`, ``);
+
+  // Per-group CSS classes
+  for (const groupId of model.groupOrder) {
+    const group = model.groups.get(groupId);
+    if (!group) continue;
+
+    const className = groupId.replace(/[^a-zA-Z0-9-_]/g, "-");
+    const styleDecls = buildGroupStyleDecls(group.style, group.containerStyle);
+
+    if (styleDecls.length > 0) {
+      lines.push(`.caption-group.${className} {`);
+      for (const decl of styleDecls) {
+        lines.push(`  ${decl}`);
+      }
+      lines.push(`}`, ``);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function buildGroupStyleDecls(
+  style: CaptionStyle,
+  containerStyle: CaptionContainerStyle,
+): string[] {
+  const decls: string[] = [];
+
+  // Typography
+  if (style.fontFamily) {
+    decls.push(`font-family: ${style.fontFamily};`);
+  }
+  if (style.fontSize) {
+    decls.push(`font-size: ${style.fontSize}px;`);
+  }
+  if (style.fontWeight) {
+    decls.push(`font-weight: ${style.fontWeight};`);
+  }
+  if (style.fontStyle && style.fontStyle !== "normal") {
+    decls.push(`font-style: ${style.fontStyle};`);
+  }
+  if (style.textDecoration && style.textDecoration !== "none") {
+    decls.push(`text-decoration: ${style.textDecoration};`);
+  }
+  if (style.textTransform && style.textTransform !== "none") {
+    decls.push(`text-transform: ${style.textTransform};`);
+  }
+  if (style.letterSpacing !== 0) {
+    decls.push(`letter-spacing: ${style.letterSpacing}em;`);
+  }
+  if (style.lineHeight) {
+    decls.push(`line-height: ${style.lineHeight};`);
+  }
+
+  // Color / fill
+  if (style.color) {
+    decls.push(`color: ${style.color};`);
+  }
+  if (style.opacity !== undefined && style.opacity !== 1) {
+    // opacity is managed by GSAP animations, but non-default base opacity can be declared
+    decls.push(`--caption-base-opacity: ${style.opacity};`);
+  }
+
+  // Stroke (via text-stroke / webkit-text-stroke)
+  if (style.strokeWidth > 0) {
+    decls.push(`-webkit-text-stroke: ${style.strokeWidth}px ${style.strokeColor};`);
+  }
+
+  // Shadows
+  if (style.shadows && style.shadows.length > 0) {
+    const shadowStr = style.shadows.map(shadowToCss).join(", ");
+    decls.push(`text-shadow: ${shadowStr};`);
+  }
+
+  // Glow (implemented as additional text-shadow)
+  if (style.glow) {
+    const glowStr = glowToCss(style.glow);
+    const existingShadow =
+      style.shadows && style.shadows.length > 0
+        ? style.shadows.map(shadowToCss).join(", ") + ", "
+        : "";
+    // Only emit if not already emitted shadows (override the text-shadow if both present)
+    if (!(style.shadows && style.shadows.length > 0)) {
+      decls.push(`text-shadow: ${glowStr};`);
+    } else {
+      // Replace the last text-shadow declaration with combined
+      const idx = decls.findLastIndex((d) => d.startsWith("text-shadow:"));
+      if (idx >= 0) {
+        decls[idx] = `text-shadow: ${existingShadow}${glowStr};`;
+      }
+    }
+  }
+
+  // Blend mode
+  if (style.blendMode && style.blendMode !== "normal") {
+    decls.push(`mix-blend-mode: ${style.blendMode};`);
+  }
+
+  // Container: background
+  if (
+    containerStyle.backgroundColor &&
+    containerStyle.backgroundColor !== "transparent" &&
+    containerStyle.backgroundOpacity > 0
+  ) {
+    const bg = hexToRgba(containerStyle.backgroundColor, containerStyle.backgroundOpacity);
+    decls.push(`background-color: ${bg};`);
+  }
+
+  // Container: padding
+  const { paddingTop, paddingRight, paddingBottom, paddingLeft } = containerStyle;
+  if (paddingTop > 0 || paddingRight > 0 || paddingBottom > 0 || paddingLeft > 0) {
+    decls.push(`padding: ${paddingTop}px ${paddingRight}px ${paddingBottom}px ${paddingLeft}px;`);
+  }
+
+  // Container: border radius
+  if (containerStyle.borderRadius > 0) {
+    decls.push(`border-radius: ${containerStyle.borderRadius}px;`);
+  }
+
+  // Container: border
+  if (containerStyle.borderWidth > 0) {
+    decls.push(
+      `border: ${containerStyle.borderWidth}px ${containerStyle.borderStyle} ${containerStyle.borderColor};`,
+    );
+  }
+
+  // Container: box shadow
+  if (containerStyle.boxShadow && containerStyle.boxShadow !== "none") {
+    decls.push(`box-shadow: ${containerStyle.boxShadow};`);
+  }
+
+  return decls;
+}
+
+function shadowToCss(shadow: CaptionShadow): string {
+  return `${shadow.offsetX}px ${shadow.offsetY}px ${shadow.blur}px ${shadow.color}`;
+}
+
+function glowToCss(glow: CaptionGlow): string {
+  // Glow is represented as a spread text-shadow with opacity applied to color
+  return `0 0 ${glow.blur}px ${hexToRgba(glow.color, glow.opacity)}`;
+}
+
+/** Converts a hex color and opacity into rgba(...) for CSS */
+function hexToRgba(color: string, opacity: number): string {
+  // If it's already rgb/rgba, just return it (can't easily inject opacity)
+  if (color.startsWith("rgb")) {
+    return color;
+  }
+  // Named colors and other non-hex values — return as-is
+  if (!color.startsWith("#")) {
+    return color;
+  }
+  // Try to parse hex
+  const hex = color.replace("#", "");
+  if (hex.length === 3 || hex.length === 6) {
+    const full =
+      hex.length === 3
+        ? hex
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : hex;
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+  }
+  return color;
+}
+
+// ---------------------------------------------------------------------------
+// JS generation
+// ---------------------------------------------------------------------------
+
+function generateJs(model: CaptionModel): string {
+  // Collect all segments across all groups in order
+  const allSegments: Array<{ text: string; start: number; end: number }> = [];
+  for (const groupId of model.groupOrder) {
+    const group = model.groups.get(groupId);
+    if (!group) continue;
+    for (const segId of group.segmentIds) {
+      const seg = model.segments.get(segId);
+      if (!seg) continue;
+      allSegments.push({ text: seg.text, start: seg.start, end: seg.end });
+    }
+  }
+
+  const transcriptJson = JSON.stringify(allSegments, null, 2);
+
+  const groupBlocks: string[] = [];
+
+  for (const groupId of model.groupOrder) {
+    const group = model.groups.get(groupId);
+    if (!group) continue;
+
+    const className = groupId.replace(/[^a-zA-Z0-9-_]/g, "-");
+
+    // Compute group start/end from its segments
+    const groupSegments = group.segmentIds
+      .map((id) => model.segments.get(id))
+      .filter((s): s is CaptionSegment => s !== undefined);
+
+    if (groupSegments.length === 0) continue;
+
+    const firstSeg = groupSegments[0];
+    const lastSeg = groupSegments[groupSegments.length - 1];
+    const groupStart = firstSeg.start;
+    const groupEnd = lastSeg.end;
+
+    const groupVar = className.replace(/[^a-zA-Z0-9_]/g, "_");
+
+    // Build word spans
+    const wordLines: string[] = groupSegments.map((seg) => {
+      const escaped = seg.text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+      const segVar = `w_${seg.id.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+      return (
+        `  const ${segVar} = document.createElement('span');` +
+        `\n  ${segVar}.className = 'word clip';` +
+        `\n  ${segVar}.textContent = '${escaped}';` +
+        `\n  ${segVar}.dataset.start = '${seg.start}';` +
+        `\n  ${segVar}.dataset.end = '${seg.end}';` +
+        `\n  groupEl_${groupVar}.appendChild(${segVar});`
+      );
+    });
+
+    // Position: if x/y non-zero, use absolute with left/top; otherwise center
+    const groupVarName = `groupEl_${groupVar}`;
+    const hasExplicitPosition = group.style.x !== 0 || group.style.y !== 0;
+
+    let positionLines: string;
+    if (hasExplicitPosition) {
+      positionLines = [
+        `  ${groupVarName}.style.left = '${group.style.x}px';`,
+        `  ${groupVarName}.style.top = '${group.style.y}px';`,
+      ].join("\n");
+    } else {
+      positionLines = [
+        `  ${groupVarName}.style.left = '50%';`,
+        `  ${groupVarName}.style.top = '80%';`,
+        `  ${groupVarName}.style.transform = 'translateX(-50%) translateY(-50%)';`,
+        `  ${groupVarName}.style.justifyContent = 'center';`,
+        `  ${groupVarName}.style.maxWidth = '90%';`,
+      ].join("\n");
+    }
+
+    const block = [
+      `// Group: ${groupId}`,
+      `const ${groupVarName} = document.createElement('div');`,
+      `${groupVarName}.className = 'caption-group clip ${className}';`,
+      `${groupVarName}.dataset.start = '${groupStart}';`,
+      `${groupVarName}.dataset.end = '${groupEnd}';`,
+      `container.appendChild(${groupVarName});`,
+      wordLines.join("\n"),
+      positionLines,
+      `// Entrance: fade in at group start`,
+      `tl.to(${groupVarName}, { opacity: 1, duration: 0.2, ease: 'power2.out' }, ${groupStart});`,
+      `// Exit: fade out at group end`,
+      `tl.to(${groupVarName}, { opacity: 0, duration: 0.2, ease: 'power2.in' }, ${groupEnd} - 0.2);`,
+    ].join("\n");
+
+    groupBlocks.push(block);
+  }
+
+  return `(function () {
+  const TRANSCRIPT = ${transcriptJson};
+
+  const container = document.getElementById('captions-container');
+  if (!container) return;
+
+  const tl = gsap.timeline({ paused: true });
+
+  ${groupBlocks.join("\n\n  ")}
+
+  if (!window.__timelines) window.__timelines = {};
+  window.__timelines["captions"] = tl;
+})();`;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function indent(text: string, spaces: number): string {
+  const pad = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line.trim() === "" ? "" : pad + line))
+    .join("\n");
+}