@bendyline/squisq 1.4.1 → 1.5.1

package/src/doc/templates/videoPullQuote.ts

@@ -17,18 +17,21 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { VideoPullQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import { getThemeFont, themedEntrance, themedFontSize } from '../utils/themeUtils.js';
+import { estimateTextHeight } from './captionUtils.js';
 
 export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateContext): Layer[] {
   const { text, attribution, backgroundVideo } = input;
+  const { viewport } = context;
 
   // Guard: backgroundVideo is required
   if (!backgroundVideo?.src) return [];
 
-  const quoteFontSize = scaledFontSize(52, context, true);
-  const attrFontSize = scaledFontSize(24, context, false);
-  const decoFontSize = scaledFontSize(200, context, true);
+  const quoteFontSize = themedFontSize(52, context, true);
+  const attrFontSize = themedFontSize(26, context, false);
+  const decoFontSize = themedFontSize(200, context, true);
+  const quoteLineHeight = 1.4;
+  const quoteYPct = attribution ? 45 : 50;
 
   const layers: Layer[] = [
     // Full-bleed background video clip
@@ -90,22 +93,29 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
           fontFamily: getThemeFont(context, 'title'),
           color: '#ffffff',
           textAlign: 'center',
-          lineHeight: 1.5,
+          lineHeight: quoteLineHeight,
           shadow: true,
         },
       },
       position: {
         x: '50%',
-        y: attribution ? '45%' : '50%',
+        y: `${quoteYPct}%`,
         anchor: 'center',
-        width: '80%',
+        width: '72%',
       },
-      animation: { type: 'fadeIn', duration: 2 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 }),
     },
   ];
 
-  // Attribution
+  // Attribution \u2014 hangs just below the quote's estimated bottom edge so
+  // the two read as one lockup instead of stranding near the bottom.
   if (attribution) {
+    const quoteWidthPx = 0.72 * viewport.width;
+    const quoteHeightPx = estimateTextHeight(text, quoteFontSize, quoteWidthPx, quoteLineHeight);
+    const attrYPct = Math.min(
+      82,
+      quoteYPct + ((quoteHeightPx / 2 + quoteFontSize * 1.7) / viewport.height) * 100,
+    );
     layers.push({
       type: 'text',
       id: 'attribution',
@@ -114,14 +124,14 @@ export function videoPullQuote(input: VideoPullQuoteInput, context: TemplateCont
         style: {
           fontSize: attrFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: 'rgba(255, 255, 255, 0.7)',
+          color: 'rgba(255, 255, 255, 0.85)',
           textAlign: 'center',
           shadow: true,
         },
       },
       position: {
         x: '50%',
-        y: '72%',
+        y: `${attrYPct}%`,
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 1.5 },

package/src/doc/templates/videoWithCaption.ts

@@ -17,8 +17,8 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { VideoWithCaptionInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import { getThemeFont, shouldUseShadow, themedFontSize } from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
 import { cleanCaption } from './captionUtils.js';
 
 export function videoWithCaption(input: VideoWithCaptionInput, context: TemplateContext): Layer[] {
@@ -35,10 +35,10 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
     videoLicense,
   } = input;
   const caption = rawCaption ? cleanCaption(rawCaption) : rawCaption;
-  const { theme, layout } = context;
+  const { theme } = context;
 
-  const captionFontSize = scaledFontSize(36, context, false);
-  const creditFontSize = scaledFontSize(16, context, false);
+  const captionFontSize = themedFontSize(30, context, false);
+  const creditFontSize = themedFontSize(16, context, false);
 
   const layers: Layer[] = [
     // Background video clip
@@ -60,26 +60,30 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
     },
   ];
 
-  // Caption text at bottom with gradient for readability
+  // Caption text with a compact translucent band. Long archival captions are
+  // clamped so they don't collide with player controls or cover the frame.
   if (caption) {
+    const bg = theme.colors.background;
+    const captionBgY =
+      captionPosition === 'top' ? '7%' : captionPosition === 'center' ? '42%' : '68%';
+    const captionY =
+      captionPosition === 'top' ? '13%' : captionPosition === 'center' ? '48%' : '74%';
+
     layers.push({
       type: 'shape',
       id: 'caption-gradient',
       content: {
         shape: 'rect',
-        fill: 'linear-gradient(0deg, rgba(0,0,0,0.7) 0%, rgba(0,0,0,0.3) 60%, transparent 100%)',
+        fill: `linear-gradient(90deg, ${withAlpha(bg, 0)}, ${withAlpha(bg, 0.78)} 16%, ${withAlpha(bg, 0.78)} 84%, ${withAlpha(bg, 0)})`,
       },
       position: {
         x: 0,
-        y: captionPosition === 'top' ? 0 : '65%',
+        y: captionBgY,
         width: '100%',
-        height: '35%',
+        height: '16%',
       },
     });
 
-    const captionY =
-      captionPosition === 'top' ? '15%' : captionPosition === 'center' ? '50%' : '82%';
-
     layers.push({
       type: 'text',
       id: 'caption',
@@ -90,14 +94,16 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
+          lineHeight: 1.18,
+          maxLines: 2,
         },
       },
       position: {
         x: '50%',
         y: captionY,
         anchor: 'center',
-        width: layout.maxTextWidth,
+        width: '78%',
       },
       animation: { type: 'fadeIn', duration: 1.5, delay: 0.5 },
     });
@@ -113,7 +119,7 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
         style: {
           fontSize: creditFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: 'rgba(255, 255, 255, 0.5)',
+          color: withAlpha(theme.colors.text, 0.65),
           textAlign: 'right',
         },
       },

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;
+}

package/src/doc/utils/nearest.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared "did-you-mean" edit-distance helpers.
+ *
+ * A leaf module (no imports) so both `doc/validate.ts` and
+ * `doc/templates/inputDescriptors.ts` can share one implementation without
+ * risking an import cycle through `templates/index.ts`.
+ */
+
+/** Levenshtein edit distance between two strings. */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array<number>(n + 1);
+  let curr = new Array<number>(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+/**
+ * Nearest candidate name by edit distance, or `undefined` when nothing is
+ * plausibly close. "Close" means distance ≤ `maxDistance` (default 2) OR
+ * ≤ 40% of the input length — the shared threshold both call sites use.
+ *
+ * @param options.map - Optional post-processor applied to the winning
+ *   candidate (e.g. `resolveTemplateName` to canonicalize an alias hit).
+ * @param options.maxDistance - Absolute distance floor for "close" (default 2).
+ */
+export function nearestName(
+  input: string,
+  candidates: Iterable<string>,
+  options?: { map?: (best: string) => string; maxDistance?: number },
+): string | undefined {
+  const maxDistance = options?.maxDistance ?? 2;
+  let best: string | undefined;
+  let bestDist = Infinity;
+  const lower = input.toLowerCase();
+  for (const candidate of candidates) {
+    const dist = levenshtein(lower, candidate.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+  if (best && (bestDist <= maxDistance || bestDist <= Math.ceil(input.length * 0.4))) {
+    return options?.map ? options.map(best) : best;
+  }
+  return undefined;
+}