@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/utils/animationUtils.ts

@@ -8,7 +8,12 @@
  * This is shared code used by both site and efb-app doc renderers.
  */
 
-import type { Animation, AnimationType, TransitionType } from '../../schemas/Doc.js';
+import type {
+  Animation,
+  AnimationType,
+  TransitionDirection,
+  TransitionType,
+} from '../../schemas/Doc.js';
 
 interface AnimationResult {
   /** CSS class name to apply */
@@ -112,9 +117,268 @@ export function getDefaultAnimationDuration(type: AnimationType): number {
 /**
  * Get transition class for slide entry/exit.
  */
-export function getTransitionClass(type: TransitionType, entering: boolean): string {
+export function getTransitionClass(
+  type: TransitionType,
+  entering: boolean,
+  direction?: TransitionDirection,
+): string {
+  if (type === 'cut') return '';
   const mode = entering ? 'enter' : 'exit';
-  return `transition-${type}-${mode}`;
+  return `transition-${getTransitionVisualClass(type, direction)}-${mode}`;
+}
+
+type TransitionVisualClass =
+  | 'cut'
+  | 'fade'
+  | 'dissolve'
+  | 'pushLeft'
+  | 'pushRight'
+  | 'pushUp'
+  | 'pushDown'
+  | 'wipeLeft'
+  | 'wipeRight'
+  | 'wipeUp'
+  | 'wipeDown'
+  | 'splitHorizontal'
+  | 'splitVertical'
+  | 'revealLeft'
+  | 'revealRight'
+  | 'revealUp'
+  | 'revealDown'
+  | 'random'
+  | 'randomBarsHorizontal'
+  | 'randomBarsVertical'
+  | 'shapeCircle'
+  | 'shapeDiamond'
+  | 'shapePlus'
+  | 'uncoverLeft'
+  | 'uncoverRight'
+  | 'uncoverUp'
+  | 'uncoverDown'
+  | 'coverLeft'
+  | 'coverRight'
+  | 'coverUp'
+  | 'coverDown'
+  | 'zoom'
+  | 'panLeft'
+  | 'panRight'
+  | 'panUp'
+  | 'panDown'
+  | 'flash'
+  | 'newsflash'
+  | 'fallOver'
+  | 'drape'
+  | 'curtains'
+  | 'wind'
+  | 'prestige'
+  | 'fracture'
+  | 'crush'
+  | 'peelOff'
+  | 'pageCurl'
+  | 'pageCurlDouble'
+  | 'pageCurlSingle'
+  | 'airplane'
+  | 'origami'
+  | 'checkerboard'
+  | 'blindsHorizontal'
+  | 'blindsVertical'
+  | 'clock'
+  | 'ripple'
+  | 'honeycomb'
+  | 'glitter'
+  | 'vortex'
+  | 'shred'
+  | 'switch'
+  | 'flip'
+  | 'gallery'
+  | 'cube'
+  | 'doors'
+  | 'box'
+  | 'ferrisWheel'
+  | 'conveyor'
+  | 'rotate'
+  | 'window'
+  | 'orbit'
+  | 'flyThrough'
+  | 'morph'
+  | 'combHorizontal'
+  | 'combVertical'
+  | 'pullLeft'
+  | 'pullRight'
+  | 'pullUp'
+  | 'pullDown'
+  | 'stripsLeft'
+  | 'stripsRight'
+  | 'stripsUp'
+  | 'stripsDown'
+  | 'wedge'
+  | 'wheel'
+  | 'wheelReverse'
+  | 'prism'
+  | 'warp'
+  | 'slideLeft'
+  | 'slideRight'
+  | 'slideUp'
+  | 'slideDown';
+
+const TRANSITION_VISUAL_CLASS_BY_TYPE: Record<TransitionType, TransitionVisualClass> = {
+  airplane: 'airplane',
+  blinds: 'blindsHorizontal',
+  box: 'box',
+  checker: 'checkerboard',
+  checkerboard: 'checkerboard',
+  circle: 'shapeCircle',
+  clock: 'clock',
+  comb: 'combHorizontal',
+  conveyor: 'conveyor',
+  cover: 'coverLeft',
+  crush: 'crush',
+  cube: 'cube',
+  curtains: 'curtains',
+  cut: 'cut',
+  diamond: 'shapeDiamond',
+  dissolve: 'dissolve',
+  doors: 'doors',
+  drape: 'drape',
+  fade: 'fade',
+  fallOver: 'fallOver',
+  ferris: 'ferrisWheel',
+  ferrisWheel: 'ferrisWheel',
+  flash: 'flash',
+  flip: 'flip',
+  flyThrough: 'flyThrough',
+  flythrough: 'flyThrough',
+  fracture: 'fracture',
+  gallery: 'gallery',
+  glitter: 'glitter',
+  honeycomb: 'honeycomb',
+  morph: 'morph',
+  newsflash: 'newsflash',
+  orbit: 'orbit',
+  origami: 'origami',
+  pageCurl: 'pageCurl',
+  pageCurlDouble: 'pageCurlDouble',
+  pageCurlSingle: 'pageCurlSingle',
+  pan: 'panLeft',
+  peelOff: 'peelOff',
+  plus: 'shapePlus',
+  prestige: 'prestige',
+  prism: 'prism',
+  pull: 'pullLeft',
+  push: 'pushLeft',
+  random: 'random',
+  randomBar: 'randomBarsHorizontal',
+  randomBars: 'randomBarsVertical',
+  reveal: 'revealLeft',
+  ripple: 'ripple',
+  rotate: 'rotate',
+  shape: 'shapeCircle',
+  shred: 'shred',
+  slideDown: 'slideDown',
+  slideLeft: 'slideLeft',
+  slideRight: 'slideRight',
+  slideUp: 'slideUp',
+  split: 'splitHorizontal',
+  strips: 'stripsLeft',
+  switch: 'switch',
+  uncover: 'uncoverLeft',
+  vortex: 'vortex',
+  warp: 'warp',
+  wedge: 'wedge',
+  wheel: 'wheel',
+  wheelReverse: 'wheelReverse',
+  wind: 'wind',
+  window: 'window',
+  wipe: 'wipeLeft',
+  zoom: 'zoom',
+};
+
+function getTransitionVisualClass(
+  type: TransitionType,
+  direction?: TransitionDirection,
+): TransitionVisualClass {
+  switch (type) {
+    case 'randomBars':
+    case 'randomBar':
+      return axisClass('randomBars', direction, type === 'randomBar' ? 'Horizontal' : 'Vertical');
+    case 'comb':
+      return axisClass('comb', direction, 'Horizontal');
+    case 'blinds':
+      return axisClass('blinds', direction, 'Horizontal');
+    case 'split':
+      return axisClass('split', direction, 'Horizontal');
+    case 'push':
+      return directionalClass('push', direction, 'Left');
+    case 'wipe':
+      return directionalClass('wipe', direction, 'Left');
+    case 'cover':
+      return directionalClass('cover', direction, 'Left');
+    case 'uncover':
+      return directionalClass('uncover', direction, 'Left');
+    case 'pull':
+      return directionalClass('pull', direction, 'Left');
+    case 'reveal':
+      return directionalClass('reveal', direction, 'Left');
+    case 'strips':
+      return directionalClass('strips', direction, 'Left');
+    case 'pan':
+      return directionalClass('pan', direction, 'Left');
+    default:
+      return TRANSITION_VISUAL_CLASS_BY_TYPE[type];
+  }
+}
+
+function directionalClass(
+  prefix: 'cover' | 'pan' | 'pull' | 'push' | 'reveal' | 'strips' | 'uncover' | 'wipe',
+  direction: TransitionDirection | undefined,
+  fallback: 'Left' | 'Right' | 'Up' | 'Down',
+): TransitionVisualClass {
+  const suffix = directionSuffix(direction, fallback);
+  return `${prefix}${suffix}` as TransitionVisualClass;
+}
+
+function axisClass(
+  prefix: 'blinds' | 'comb' | 'randomBars' | 'split',
+  direction: TransitionDirection | undefined,
+  fallback: 'Horizontal' | 'Vertical',
+): TransitionVisualClass {
+  const suffix = axisSuffix(direction, fallback);
+  return `${prefix}${suffix}` as TransitionVisualClass;
+}
+
+function directionSuffix(
+  direction: TransitionDirection | undefined,
+  fallback: 'Left' | 'Right' | 'Up' | 'Down',
+): 'Left' | 'Right' | 'Up' | 'Down' {
+  switch (direction) {
+    case 'right':
+      return 'Right';
+    case 'up':
+      return 'Up';
+    case 'down':
+      return 'Down';
+    case 'left':
+    default:
+      return fallback;
+  }
+}
+
+function axisSuffix(
+  direction: TransitionDirection | undefined,
+  fallback: 'Horizontal' | 'Vertical',
+): 'Horizontal' | 'Vertical' {
+  switch (direction) {
+    case 'vertical':
+    case 'up':
+    case 'down':
+      return 'Vertical';
+    case 'horizontal':
+    case 'left':
+    case 'right':
+      return 'Horizontal';
+    default:
+      return fallback;
+  }
 }
 
 /**

package/src/doc/utils/applyRenderStyle.ts

@@ -0,0 +1,113 @@
+/**
+ * Render-style post-pass — applies a theme's mechanical motion defaults to
+ * template-generated layers.
+ *
+ * This is the intent-free half of theme motion (see `themedEntrance` in
+ * [themeUtils.ts](./themeUtils.ts) for the intent-bearing half): it never
+ * decides *what kind* of entrance a layer gets, only
+ *
+ *  1. scales existing animation durations/delays by the theme's
+ *     `style.animationSpeed` multiplier (1.4 = calmer/slower, 0.7 = snappier,
+ *     1.0 = no-op), and
+ *  2. gives full-bleed cover imagery with no authored animation a gentle,
+ *     deterministic Ken Burns when the theme opts into ambient motion.
+ *
+ * Applied ONLY to template-generated layers — raw authored `block.layers`
+ * are never touched, and an explicit `animation` (including
+ * `{ type: 'none' }`) always wins.
+ */
+
+import type { Layer, Animation } from '../../schemas/Doc.js';
+import type { Theme } from '../../schemas/Theme.js';
+import { SeededRandom, hashString } from '../../random/index.js';
+
+/** The gentle Ken Burns variants ambient motion rotates between. */
+const AMBIENT_VARIANTS: readonly Animation[] = [
+  { type: 'slowZoom', direction: 'in' },
+  { type: 'slowZoom', direction: 'out' },
+  { type: 'slowZoom', panDirection: 'left' },
+  { type: 'slowZoom', panDirection: 'right' },
+];
+
+/** Minimum ambient Ken Burns duration — short blocks shouldn't rush the pan. */
+const MIN_AMBIENT_DURATION_SECONDS = 8;
+
+function isZeroish(v: number | string | undefined): boolean {
+  return v === 0 || v === '0' || v === '0%';
+}
+
+/**
+ * Full-bleed cover imagery is the only shape we can safely blanket-animate:
+ * anything smaller (strips, insets, grid cells) was placed deliberately and
+ * a zoom would fight the composition.
+ */
+function isFullBleedCoverMedia(layer: Layer): boolean {
+  if (layer.type !== 'image' && layer.type !== 'video') return false;
+  const { position } = layer;
+  if (!isZeroish(position.x) || !isZeroish(position.y)) return false;
+  if (position.width !== '100%' || position.height !== '100%') return false;
+  const fit = (layer.content as { fit?: string }).fit;
+  return fit === undefined || fit === 'cover';
+}
+
+/**
+ * Whether the theme asks for ambient Ken Burns on otherwise-static imagery.
+ * `defaultImageAnimation: 'slowZoom'` is treated as an alias for the boolean
+ * (that's what themes authoring it were reaching for).
+ */
+export function themeWantsAmbientMotion(theme: Theme): boolean {
+  return (
+    theme.renderStyle.ambientMotion === true ||
+    theme.renderStyle.defaultImageAnimation === 'slowZoom'
+  );
+}
+
+/**
+ * Apply the theme's mechanical motion defaults to a block's
+ * template-generated layers. Pure: returns new layer objects where a change
+ * applies and the original objects where none does.
+ *
+ * @param layers Template-generated layers (never raw authored layers)
+ * @param block  The source block — supplies the ambient-motion seed and duration
+ * @param theme  Resolved theme
+ */
+export function applyRenderStyleToLayers(
+  layers: Layer[],
+  block: { id: string; duration?: number },
+  theme: Theme,
+): Layer[] {
+  const speed = theme.style.animationSpeed ?? 1.0;
+  const ambient = themeWantsAmbientMotion(theme);
+  if (speed === 1.0 && !ambient) return layers;
+
+  return layers.map((layer) => {
+    let animation = layer.animation;
+
+    // Ambient Ken Burns for full-bleed cover imagery with no authored
+    // animation. Deterministic per block+layer so re-renders, export
+    // frames, and screenshots always agree.
+    if (!animation && ambient && isFullBleedCoverMedia(layer)) {
+      const rng = new SeededRandom(hashString(`${block.id}:${layer.id}`));
+      const variant = rng.pickRequired(AMBIENT_VARIANTS as Animation[]);
+      animation = {
+        ...variant,
+        duration: Math.max(MIN_AMBIENT_DURATION_SECONDS, block.duration ?? 0),
+      };
+    }
+
+    if (!animation || animation.type === 'none') {
+      return animation === layer.animation ? layer : { ...layer, animation };
+    }
+
+    // Speed scaling — single site so templates never double-scale.
+    if (speed !== 1.0) {
+      animation = {
+        ...animation,
+        ...(animation.duration != null ? { duration: animation.duration * speed } : {}),
+        ...(animation.delay != null ? { delay: animation.delay * speed } : {}),
+      };
+    }
+
+    return animation === layer.animation ? layer : { ...layer, animation };
+  });
+}

package/src/doc/utils/imageTreatment.ts

@@ -0,0 +1,70 @@
+/**
+ * Image treatment → CSS filter derivation.
+ *
+ * Treatments are theme-level photographic grades (see `ImageTreatment` in
+ * [Doc.ts](../../schemas/Doc.ts)). They compile to plain CSS `filter`
+ * functions so the same string works on a foreignObject `<img>`, an SVG
+ * `<image>` element, and in headless frame capture — no SVG filter defs to
+ * coordinate, no renderer-specific code paths.
+ */
+
+import type { ImageTreatment } from '../../schemas/Doc.js';
+import { hexHueDegrees } from '../../schemas/colorUtils.js';
+
+/** Sepia's intrinsic tint hue (deg) — duotone rotates from here to the target. */
+const SEPIA_HUE_DEGREES = 40;
+
+const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
+const r2 = (v: number) => Math.round(v * 100) / 100;
+
+/**
+ * Build the CSS `filter` value for a treatment and/or blur.
+ * Returns `undefined` when there is nothing to apply.
+ */
+export function cssFilterForTreatment(
+  treatment?: ImageTreatment,
+  blur?: number,
+): string | undefined {
+  const parts: string[] = [];
+
+  if (blur != null && blur > 0) {
+    parts.push(`blur(${Math.round(blur)}px)`);
+  }
+
+  if (treatment && treatment.type !== 'none') {
+    const s = clamp01(treatment.strength ?? 0.6);
+    switch (treatment.type) {
+      case 'mono':
+        // Archival black & white with a whisper of contrast to keep depth.
+        parts.push(`grayscale(${r2(s)})`, `contrast(${r2(1 + 0.05 * s)})`);
+        break;
+      case 'duotone': {
+        // Classic CSS duotone approximation: flatten to gray, tint through
+        // sepia (intrinsic hue ~40°), rotate to the target hue, re-saturate.
+        const hue = hexHueDegrees(treatment.color ?? '#3d5a80');
+        parts.push(
+          'grayscale(1)',
+          `sepia(${r2(Math.max(0.35, s))})`,
+          `hue-rotate(${Math.round(hue - SEPIA_HUE_DEGREES)}deg)`,
+          `saturate(${r2(1 + s)})`,
+        );
+        break;
+      }
+      case 'warm':
+        // Partial sepia is a well-behaved warmer; slight saturation lift.
+        parts.push(`sepia(${r2(0.4 * s)})`, `saturate(${r2(1 + 0.15 * s)})`);
+        break;
+      case 'cool':
+        // Desaturate a touch and nudge warm tones toward magenta/blue —
+        // small rotations read as a grade, large ones wreck hues.
+        parts.push(
+          `saturate(${r2(1 - 0.25 * s)})`,
+          `hue-rotate(${Math.round(-12 * s)}deg)`,
+          `contrast(${r2(1 + 0.06 * s)})`,
+        );
+        break;
+    }
+  }
+
+  return parts.length > 0 ? parts.join(' ') : undefined;
+}