@shotstack/shotstack-canvas 1.0.2

package/src/core/animations.ts

@@ -0,0 +1,570 @@
+import { DrawOp, Glyph, ShapedLine } from "../types";
+
+export type AnimationInput = {
+  preset?: "typewriter" | "fadeIn" | "slideIn" | "shift" | "ascend" | "movingLetters";
+  speed: number;
+  duration?: number;
+  style?: "character" | "word";
+  direction?: "left" | "right" | "up" | "down";
+};
+
+const DECORATION_DONE_THRESHOLD = 0.999;
+
+export function applyAnimation(
+  ops: DrawOp[],
+  lines: ShapedLine[],
+  p: { t: number; fontSize: number; anim?: AnimationInput }
+): DrawOp[] {
+  if (!p.anim || !p.anim.preset) return ops;
+
+  const { preset } = p.anim;
+  const totalGlyphs = lines.reduce((s, l) => s + l.glyphs.length, 0);
+  const duration = p.anim.duration ?? Math.max(0.3, totalGlyphs / 30 / p.anim.speed);
+  const progress = Math.max(0, Math.min(1, p.t / duration));
+
+  switch (preset) {
+    case "typewriter":
+      return applyTypewriterAnimation(
+        ops,
+        lines,
+        progress,
+        p.anim.style,
+        p.fontSize,
+        p.t,
+        duration
+      );
+    case "fadeIn":
+      return applyFadeInAnimation(ops, progress);
+    case "slideIn":
+      return applySlideInAnimation(ops, progress, p.anim.direction ?? "left", p.fontSize);
+    case "shift":
+      return applyShiftAnimation(
+        ops,
+        lines,
+        progress,
+        p.anim.direction ?? "left",
+        p.fontSize,
+        p.anim.style,
+        duration
+      );
+    case "ascend":
+      return applyAscendAnimation(
+        ops,
+        lines,
+        progress,
+        p.anim.direction ?? "up",
+        p.fontSize,
+        duration
+      );
+    case "movingLetters":
+      return applyMovingLettersAnimation(ops, progress, p.anim.direction ?? "up", p.fontSize);
+    default:
+      return ops;
+  }
+}
+
+// ---- helpers
+const isShadowFill = (op: DrawOp) => op.op === "FillPath" && (op as any).isShadow === true;
+const isGlyphFill = (op: DrawOp) => op.op === "FillPath" && !(op as any).isShadow === true;
+
+// Try to derive a text color from the first fill we find
+function getTextColorFromOps(ops: DrawOp[]): string {
+  for (const op of ops) {
+    if (op.op === "FillPath") {
+      const fill: any = (op as any).fill;
+      if (fill?.kind === "solid") return fill.color;
+      if (
+        (fill?.kind === "linear" || fill?.kind === "radial") &&
+        Array.isArray(fill.stops) &&
+        fill.stops.length
+      ) {
+        return fill.stops[fill.stops.length - 1].color || "#000000";
+      }
+    }
+  }
+  return "#000000";
+}
+
+// ---------- TYPEWRITER ----------
+function applyTypewriterAnimation(
+  ops: DrawOp[],
+  lines: ShapedLine[],
+  progress: number,
+  style: "character" | "word" | undefined,
+  fontSize: number,
+  time: number,
+  duration: number
+): DrawOp[] {
+  const byWord = style === "word";
+
+  if (byWord) {
+    const wordSegments = getWordSegments(lines);
+    const totalWords = wordSegments.length;
+    const visibleWords = Math.floor(progress * totalWords);
+    if (visibleWords === 0) return ops.filter((x) => x.op === "BeginFrame");
+
+    let totalVisibleGlyphs = 0;
+    for (let i = 0; i < Math.min(visibleWords, wordSegments.length); i++) {
+      totalVisibleGlyphs += wordSegments[i].glyphCount;
+    }
+    const visibleOpsRaw = sliceGlyphOps(ops, totalVisibleGlyphs);
+
+    const visibleOps =
+      progress >= DECORATION_DONE_THRESHOLD
+        ? visibleOpsRaw
+        : visibleOpsRaw.filter((o) => o.op !== "DecorationLine");
+
+    if (progress < 1 && totalVisibleGlyphs > 0) {
+      return addTypewriterCursor(visibleOps, totalVisibleGlyphs, fontSize, time);
+    }
+    return visibleOps;
+  } else {
+    const totalGlyphs = lines.reduce((s, l) => s + l.glyphs.length, 0);
+    const visibleGlyphs = Math.floor(progress * totalGlyphs);
+    if (visibleGlyphs === 0) return ops.filter((x) => x.op === "BeginFrame");
+
+    const visibleOpsRaw = sliceGlyphOps(ops, visibleGlyphs);
+
+    const visibleOps =
+      progress >= DECORATION_DONE_THRESHOLD
+        ? visibleOpsRaw
+        : visibleOpsRaw.filter((o) => o.op !== "DecorationLine");
+
+    if (progress < 1 && visibleGlyphs > 0) {
+      return addTypewriterCursor(visibleOps, visibleGlyphs, fontSize, time);
+    }
+    return visibleOps;
+  }
+}
+
+// ---------- ASCEND ----------
+function applyAscendAnimation(
+  ops: DrawOp[],
+  lines: ShapedLine[],
+  progress: number,
+  direction: "left" | "right" | "up" | "down",
+  fontSize: number,
+  duration: number
+): DrawOp[] {
+  const wordSegments = getWordSegments(lines);
+  const totalWords = wordSegments.length;
+  if (totalWords === 0) return ops;
+
+  const result: DrawOp[] = [];
+  let glyphIndex = 0;
+
+  for (const op of ops) {
+    if (op.op === "BeginFrame") {
+      result.push(op);
+      break;
+    }
+  }
+
+  for (const op of ops) {
+    if (op.op === "FillPath" || op.op === "StrokePath") {
+      // which word owns this glyph
+      let wordIndex = -1,
+        acc = 0;
+      for (let i = 0; i < wordSegments.length; i++) {
+        const gcount = wordSegments[i].glyphCount;
+        if (glyphIndex >= acc && glyphIndex < acc + gcount) {
+          wordIndex = i;
+          break;
+        }
+        acc += gcount;
+      }
+      if (wordIndex >= 0) {
+        const startF = (wordIndex / Math.max(1, totalWords)) * (duration / duration);
+        const endF = Math.min(1, startF + 0.3);
+        if (progress >= endF) {
+          result.push(op);
+        } else if (progress > startF) {
+          const local = (progress - startF) / Math.max(1e-6, endF - startF);
+          const ease = easeOutCubic(Math.min(1, local));
+          const startOffset = direction === "up" ? fontSize * 0.4 : -fontSize * 0.4;
+          const animated: any = { ...op, y: op.y + startOffset * (1 - ease) };
+          if (op.op === "FillPath") {
+            if (animated.fill.kind === "solid")
+              animated.fill = { ...animated.fill, opacity: animated.fill.opacity * ease };
+            else animated.fill = { ...animated.fill, opacity: (animated.fill.opacity ?? 1) * ease };
+          } else {
+            animated.opacity = animated.opacity * ease;
+          }
+          result.push(animated);
+        }
+      }
+      if (isGlyphFill(op)) glyphIndex++;
+    } else if (op.op === "DecorationLine") {
+      if (progress >= DECORATION_DONE_THRESHOLD) {
+        result.push(op);
+      }
+    }
+  }
+  return result;
+}
+
+// ---------- SHIFT ----------
+function applyShiftAnimation(
+  ops: DrawOp[],
+  lines: ShapedLine[],
+  progress: number,
+  direction: "left" | "right" | "up" | "down",
+  fontSize: number,
+  style: "character" | "word" | undefined,
+  duration: number
+): DrawOp[] {
+  const byWord = style === "word";
+  const startOffsets = {
+    left: { x: fontSize * 0.6, y: 0 },
+    right: { x: -fontSize * 0.6, y: 0 },
+    up: { x: 0, y: fontSize * 0.6 },
+    down: { x: 0, y: -fontSize * 0.6 },
+  };
+  const offset = startOffsets[direction];
+
+  const wordSegments = byWord ? getWordSegments(lines) : [];
+  const totalGlyphs = lines.reduce((s, l) => s + l.glyphs.length, 0);
+  const totalUnits = byWord ? wordSegments.length : totalGlyphs;
+  if (totalUnits === 0) return ops;
+
+  const result: DrawOp[] = [];
+  for (const op of ops) {
+    if (op.op === "BeginFrame") {
+      result.push(op);
+      break;
+    }
+  }
+
+  const windowDuration = 0.3; // each unit animates for 0.3s of total duration
+  const overlapFactor = 0.7; // overlapping reveal
+  const staggerDelay = (duration * overlapFactor) / Math.max(1, totalUnits - 1);
+
+  const windowFor = (unitIdx: number) => {
+    const startTime = unitIdx * staggerDelay;
+    const startF = startTime / duration;
+    const endF = Math.min(1, (startTime + windowDuration) / duration);
+    return { startF, endF };
+  };
+
+  let glyphIndex = 0;
+  for (const op of ops) {
+    if (op.op !== "FillPath" && op.op !== "StrokePath") {
+      if (op.op === "DecorationLine" && progress > 0.8) result.push(op);
+      continue;
+    }
+
+    let unitIndex: number;
+    if (!byWord) {
+      unitIndex = glyphIndex;
+    } else {
+      let wordIndex = -1,
+        acc = 0;
+      for (let i = 0; i < wordSegments.length; i++) {
+        const gcount = wordSegments[i].glyphCount;
+        if (glyphIndex >= acc && glyphIndex < acc + gcount) {
+          wordIndex = i;
+          break;
+        }
+        acc += gcount;
+      }
+      unitIndex = Math.max(0, wordIndex);
+    }
+
+    const { startF, endF } = windowFor(unitIndex);
+
+    if (progress <= startF) {
+      const animated: any = { ...op, x: op.x + offset.x, y: op.y + offset.y };
+      if (op.op === "FillPath") {
+        if (animated.fill.kind === "solid") animated.fill = { ...animated.fill, opacity: 0 };
+        else animated.fill = { ...animated.fill, opacity: 0 };
+      } else {
+        animated.opacity = 0;
+      }
+      result.push(animated);
+    } else if (progress >= endF) {
+      result.push(op);
+    } else {
+      const local = (progress - startF) / Math.max(1e-6, endF - startF);
+      const ease = easeOutCubic(Math.min(1, local));
+      const dx = offset.x * (1 - ease);
+      const dy = offset.y * (1 - ease);
+      const animated: any = { ...op, x: op.x + dx, y: op.y + dy };
+
+      if (op.op === "FillPath") {
+        const targetOpacity =
+          animated.fill.kind === "solid" ? animated.fill.opacity : animated.fill.opacity ?? 1;
+        if (animated.fill.kind === "solid")
+          animated.fill = { ...animated.fill, opacity: targetOpacity * ease };
+        else animated.fill = { ...animated.fill, opacity: targetOpacity * ease };
+      } else {
+        animated.opacity = animated.opacity * ease;
+      }
+      result.push(animated);
+    }
+
+    if (isGlyphFill(op)) glyphIndex++;
+  }
+  return result;
+}
+
+// ---------- FADE / SLIDE / WAVE ----------
+function applyFadeInAnimation(ops: DrawOp[], progress: number): DrawOp[] {
+  const alpha = easeOutQuad(progress);
+  const scale = 0.95 + 0.05 * alpha;
+  return scaleAndFade(ops, alpha, scale);
+}
+function applySlideInAnimation(
+  ops: DrawOp[],
+  progress: number,
+  direction: "left" | "right" | "up" | "down",
+  fontSize: number
+): DrawOp[] {
+  const easeProgress = easeOutCubic(progress);
+  const shift = shiftFor(1 - easeProgress, direction, fontSize * 2);
+  const alpha = easeOutQuad(progress);
+  return translateGlyphOps(ops, shift.dx, shift.dy, alpha);
+}
+function applyMovingLettersAnimation(
+  ops: DrawOp[],
+  progress: number,
+  direction: "left" | "right" | "up" | "down",
+  fontSize: number
+): DrawOp[] {
+  const amp = fontSize * 0.3;
+  return waveTransform(ops, direction, amp, progress);
+}
+
+// ---------- word segmentation / slicing ----------
+function getWordSegments(lines: ShapedLine[]) {
+  const segments: any = [];
+  let totalGlyphIndex = 0;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const line = lines[lineIndex];
+    const words = segmentLineBySpaces(line);
+    for (const word of words) {
+      if (word.length > 0)
+        segments.push({ startGlyph: totalGlyphIndex, glyphCount: word.length, lineIndex });
+      totalGlyphIndex += word.length;
+    }
+  }
+  return segments;
+}
+function segmentLineBySpaces(line: ShapedLine): Glyph[][] {
+  const words: Glyph[][] = [];
+  let current: Glyph[] = [];
+  for (const g of line.glyphs) {
+    const isSpace = g.char === " " || g.char === "\t" || g.char === "\n";
+    if (isSpace) {
+      if (current.length) {
+        words.push([...current]);
+        current = [];
+      }
+    } else {
+      current.push(g);
+    }
+  }
+  if (current.length) words.push(current);
+  return words;
+}
+
+/** Include BOTH stroke+fill for the first `maxGlyphs` glyphs; nothing from later glyphs.
+ *  Stroke is only included if its corresponding fill will be shown (so it never appears early). */
+function sliceGlyphOps(ops: DrawOp[], maxGlyphs: number): DrawOp[] {
+  const result: DrawOp[] = [];
+  let glyphCount = 0;
+  let foundGlyphs = false;
+
+  for (const op of ops) {
+    if (op.op === "BeginFrame") {
+      result.push(op);
+      continue;
+    }
+
+    if (op.op === "FillPath" && !isShadowFill(op)) {
+      if (glyphCount < maxGlyphs) {
+        result.push(op);
+        foundGlyphs = true;
+      }
+      glyphCount++; // count only real glyph fills
+      continue;
+    }
+
+    if (op.op === "StrokePath") {
+      // Include stroke only if the upcoming fill is within range
+      if (glyphCount < maxGlyphs) result.push(op);
+      continue;
+    }
+
+    if (op.op === "FillPath" && isShadowFill(op)) {
+      if (glyphCount < maxGlyphs) result.push(op);
+      continue;
+    }
+
+    if (op.op === "DecorationLine" && foundGlyphs) {
+      result.push(op);
+      continue;
+    }
+  }
+
+  return result;
+}
+
+function addTypewriterCursor(
+  ops: DrawOp[],
+  glyphCount: number,
+  fontSize: number,
+  time: number
+): DrawOp[] {
+  const blinkRate = 2;
+  const cursorVisible = Math.floor(time * blinkRate * 2) % 2 === 0;
+  if (!cursorVisible || glyphCount === 0) return ops;
+
+  let last: DrawOp | null = null;
+  let count = 0;
+  for (const op of ops) {
+    if (op.op === "FillPath" && !isShadowFill(op)) {
+      count++;
+      if (count === glyphCount) {
+        last = op;
+        break;
+      }
+    }
+  }
+  if (last && last.op === "FillPath") {
+    const color = getTextColorFromOps(ops);
+    const cursorX = last.x + fontSize * 0.5;
+    const cursorY = last.y;
+
+    const cursorOp: DrawOp = {
+      op: "DecorationLine",
+      from: { x: cursorX, y: cursorY - fontSize * 0.7 },
+      to: { x: cursorX, y: cursorY + fontSize * 0.1 },
+      width: Math.max(2, fontSize / 25),
+      color,
+      opacity: 1,
+    };
+    return [...ops, cursorOp];
+  }
+  return ops;
+}
+
+// ---------- transforms ----------
+function scaleAndFade(ops: DrawOp[], alpha: number, scale: number): DrawOp[] {
+  let cx = 0,
+    cy = 0,
+    n = 0;
+  ops.forEach((op) => {
+    if (op.op === "FillPath") {
+      cx += op.x;
+      cy += op.y;
+      n++;
+    }
+  });
+  if (n > 0) {
+    cx /= n;
+    cy /= n;
+  }
+
+  return ops.map((op) => {
+    if (op.op === "FillPath") {
+      const out: any = { ...op };
+      if (out.fill.kind === "solid") out.fill = { ...out.fill, opacity: out.fill.opacity * alpha };
+      else out.fill = { ...out.fill, opacity: (out.fill.opacity ?? 1) * alpha };
+      if (scale !== 1 && n > 0) {
+        const dx = op.x - cx,
+          dy = op.y - cy;
+        out.x = cx + dx * scale;
+        out.y = cy + dy * scale;
+      }
+      return out;
+    }
+    if (op.op === "StrokePath") {
+      const out: any = { ...op, opacity: op.opacity * alpha };
+      if (scale !== 1 && n > 0) {
+        const dx = op.x - cx,
+          dy = op.y - cy;
+        out.x = cx + dx * scale;
+        out.y = cy + dy * scale;
+      }
+      return out;
+    }
+    if (op.op === "DecorationLine") return { ...op, opacity: op.opacity * alpha };
+    return op;
+  });
+}
+
+function translateGlyphOps(ops: DrawOp[], dx: number, dy: number, alpha: number = 1): DrawOp[] {
+  return ops.map((op) => {
+    if (op.op === "FillPath") {
+      const out: any = { ...op, x: op.x + dx, y: op.y + dy };
+      if (alpha < 1) {
+        if (out.fill.kind === "solid")
+          out.fill = { ...out.fill, opacity: out.fill.opacity * alpha };
+        else out.fill = { ...out.fill, opacity: (out.fill.opacity ?? 1) * alpha };
+      }
+      return out;
+    }
+    if (op.op === "StrokePath")
+      return { ...op, x: op.x + dx, y: op.y + dy, opacity: op.opacity * alpha };
+    if (op.op === "DecorationLine") {
+      return {
+        ...op,
+        from: { x: op.from.x + dx, y: op.from.y + dy },
+        to: { x: op.to.x + dx, y: op.to.y + dy },
+        opacity: op.opacity * alpha,
+      };
+    }
+    return op;
+  });
+}
+
+function waveTransform(
+  ops: DrawOp[],
+  dir: "left" | "right" | "up" | "down",
+  amp: number,
+  p: number
+): DrawOp[] {
+  let glyphIndex = 0;
+  return ops.map((op) => {
+    if (op.op === "FillPath" || op.op === "StrokePath") {
+      const phase = Math.sin((glyphIndex / 5) * Math.PI + p * Math.PI * 4);
+      const dx = dir === "left" || dir === "right" ? phase * amp * (dir === "left" ? -1 : 1) : 0;
+      const dy = dir === "up" || dir === "down" ? phase * amp * (dir === "up" ? -1 : 1) : 0;
+      const waveAlpha = Math.min(1, p * 2);
+      if (op.op === "FillPath") {
+        if (!isShadowFill(op)) glyphIndex++;
+        const out: any = { ...op, x: op.x + dx, y: op.y + dy };
+        if (out.fill.kind === "solid")
+          out.fill = { ...out.fill, opacity: out.fill.opacity * waveAlpha };
+        else out.fill = { ...out.fill, opacity: (out.fill.opacity ?? 1) * waveAlpha };
+        return out;
+      }
+      return { ...op, x: op.x + dx, y: op.y + dy, opacity: op.opacity * waveAlpha };
+    }
+    return op;
+  });
+}
+
+// ---------- misc ----------
+function shiftFor(progress: number, dir: "left" | "right" | "up" | "down", dist: number) {
+  const d = progress * dist;
+  switch (dir) {
+    case "left":
+      return { dx: -d, dy: 0 };
+    case "right":
+      return { dx: d, dy: 0 };
+    case "up":
+      return { dx: 0, dy: -d };
+    case "down":
+      return { dx: 0, dy: d };
+  }
+}
+function easeOutQuad(t: number) {
+  return t * (2 - t);
+}
+function easeOutCubic(t: number) {
+  return 1 - Math.pow(1 - t, 3);
+}
+function easeInOutQuad(t: number) {
+  return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+}

package/src/core/colors.ts

@@ -0,0 +1,11 @@
+import { RGBA } from "../types";
+
+export function parseHex6(hex: string, alpha = 1): RGBA {
+  const m = /^#?([a-f0-9]{6})$/i.exec(hex);
+  if (!m) throw new Error(`Invalid color ${hex}`);
+  const n = parseInt(m[1], 16);
+  const r = (n >> 16) & 0xff;
+  const g = (n >> 8) & 0xff;
+  const b = n & 0xff;
+  return { r, g, b, a: alpha };
+}

package/src/core/decoration.ts

@@ -0,0 +1,9 @@
+export function decorationGeometry(
+  kind: "underline" | "line-through",
+  p: { baselineY: number; fontSize: number; lineWidth: number; xStart: number }
+) {
+  const thickness = Math.max(1, Math.round(p.fontSize * 0.05));
+  let y = p.baselineY + Math.round(p.fontSize * 0.1);
+  if (kind === "line-through") y = p.baselineY - Math.round(p.fontSize * 0.3);
+  return { x1: p.xStart, x2: p.xStart + p.lineWidth, y, width: thickness };
+}