RUWIO/src/lib/kaleido.ts

// Math helpers for the kaleidoscope feature. Kept as pure data so
// the canvas2d offline renderer (lib/render.ts), the Konva live
// stage (components/CanvasStage.vue), AND the exported runtime
// (lib/exportPlayer.ts engine source — by mirroring the formulas in
// JS) all derive identical geometry from the same definitions.

import type { Layer, ClipInstance } from '@/types/scene'

/** Number of radial copies to render. Returns 1 when kaleido is off
 *  or the count is below the floor — the caller should treat 1 as
 *  "no kaleido, just render once unchanged". */
export function kaleidoCountFor(entity: { kaleido?: boolean; kaleidoCount?: number }): number {
  if (!entity.kaleido) return 1
  const n = Math.floor(entity.kaleidoCount ?? 0)
  if (n < 2) return 1
  return n
}

/** Per-copy radial angle in degrees. Index 0 → 0° (the source). */
export function kaleidoAngleDegrees(index: number, count: number): number {
  if (count <= 1) return 0
  return (index * 360) / count
}

/** ClipInstance kaleido pivot in world space. Defaults to the
 *  instance's own position when no explicit pivot is set. */
export function clipKaleidoPivot(inst: ClipInstance): { x: number; y: number } {
  const ix = inst.x ?? 0
  const iy = inst.y ?? 0
  return {
    x: inst.kaleidoPivotX ?? ix,
    y: inst.kaleidoPivotY ?? iy,
  }
}

/** Per-arm local clip time (seconds). Returns `null` when the arm is
 *  outside the clip's playable range — i.e. the arm hasn't started
 *  yet (its delayed start is still in the future) or it has already
 *  finished. Callers must skip arms where this returns null.
 *
 *  Semantics: arm `i` is delayed by `i * kaleidoOffset` seconds
 *  relative to the source. So with offset = 0.5s and four arms, at
 *  scene time `t` arm 0 shows the source frame, arm 1 shows the
 *  frame from 0.5s earlier in the clip's playback (equivalent to
 *  "arm 1 starts 0.5s after arm 0"), arm 2 from 1s earlier, etc.
 *  Before its delayed start the arm is hidden; after the clip's end
 *  it stays gone.
 */
export function clipArmLocalTime(
  inst: ClipInstance,
  baseLocal: number,
  index: number,
  trimmedDuration: number,
): number | null {
  if (trimmedDuration <= 0) return null
  const offset = inst.kaleidoOffset ?? 0
  const trimStart = inst.trimStart ?? 0
  const offsetIntoBlock = baseLocal - trimStart
  // Arm 0 (and the no-shift case) just uses the source's own clip-
  // local time; arms i>0 with a non-zero offset are delayed.
  const shifted = (index === 0 || offset === 0)
    ? offsetIntoBlock
    : offsetIntoBlock - index * offset
  const EPS = 1e-9
  if (shifted < -EPS || shifted > trimmedDuration + EPS) return null
  return trimStart + Math.max(0, Math.min(trimmedDuration, shifted))
}

/**
 * For rotateCopies=false: compute the rotated *position* of the
 * instance's anchor around the kaleido pivot. The caller then
 * translates by this rotated position (instead of the original
 * (ix, iy)) so the contents land in a circle around the pivot
 * without rotating themselves.
 */
export function clipArmTranslate(
  inst: ClipInstance,
  index: number,
  count: number,
): { x: number; y: number } {
  const ix = inst.x ?? 0
  const iy = inst.y ?? 0
  if (index === 0 || count <= 1) return { x: ix, y: iy }
  const rotateCopies = inst.kaleidoRotateCopies !== false
  if (rotateCopies) return { x: ix, y: iy }
  const { x: px, y: py } = clipKaleidoPivot(inst)
  const a = (kaleidoAngleDegrees(index, count) * Math.PI) / 180
  const dx = ix - px
  const dy = iy - py
  return {
    x: px + dx * Math.cos(a) - dy * Math.sin(a),
    y: py + dx * Math.sin(a) + dy * Math.cos(a),
  }
}

/** Bool helper: should the per-arm transform also rotate the
 *  contents (true) or only translate them around the pivot (false)?
 *  Default true mirrors the natural kaleidoscope look. Layers don't
 *  expose a toggle — they always rotate copies. */
export function shouldRotateClipCopies(inst: ClipInstance): boolean {
  return inst.kaleidoRotateCopies !== false
}

/** Convenience wrapper for the layer side, where the math is
 *  simpler (pivot is always the layer's own position, contents
 *  always rotate with the copy). */
export function layerKaleidoCount(layer: Layer): number {
  return kaleidoCountFor(layer)
}