@bendyline/squisq 1.5.0 → 1.5.2

package/src/doc/templates/tokens/__tests__/resolveTokens.test.ts

@@ -7,8 +7,9 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { resolveTokens } from '../resolveTokens';
+import { resolveTokens, collectListItems } from '../resolveTokens';
 import type { Block, TextLayer, ImageLayer } from '../../../../schemas/Doc.js';
+import type { CustomTemplateLayer } from '../../../../schemas/CustomTemplates.js';
 
 function textLayer(id: string, text: string): TextLayer {
   return {
@@ -219,3 +220,268 @@ describe('resolveTokens — purity', () => {
     expect(JSON.stringify(original)).toBe(before);
   });
 });
+
+describe('resolveTokens — {attr:key}', () => {
+  it('reads from templateOverrides first, then templateData, then metadata', () => {
+    // key present in all three → overrides wins
+    const over = resolveTokens(
+      [textLayer('a', '{attr:role}')],
+      block({
+        templateOverrides: { role: 'from-overrides' },
+        templateData: { role: 'from-data' },
+        metadata: { role: 'from-metadata' },
+      }),
+    );
+    expect((over[0] as TextLayer).content.text).toBe('from-overrides');
+
+    // absent from overrides → templateData wins over metadata
+    const data = resolveTokens(
+      [textLayer('a', '{attr:role}')],
+      block({ templateData: { role: 'from-data' }, metadata: { role: 'from-metadata' } }),
+    );
+    expect((data[0] as TextLayer).content.text).toBe('from-data');
+
+    // only metadata has it
+    const meta = resolveTokens(
+      [textLayer('a', '{attr:role}')],
+      block({ metadata: { role: 'from-metadata' } }),
+    );
+    expect((meta[0] as TextLayer).content.text).toBe('from-metadata');
+  });
+
+  it('stringifies non-string templateData values', () => {
+    const layers = resolveTokens(
+      [textLayer('a', 'n={attr:count}')],
+      block({ templateData: { count: 42 } }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('n=42');
+  });
+
+  it('collapses a missing attr to empty string', () => {
+    const layers = resolveTokens([textLayer('a', '[{attr:missing}]')], block());
+    expect((layers[0] as TextLayer).content.text).toBe('[]');
+  });
+});
+
+describe('resolveTokens — pipe defaults', () => {
+  it('uses the default when {title} is empty, the value when present', () => {
+    const empty = resolveTokens([textLayer('a', '{title|Untitled}')], block({ title: undefined }));
+    expect((empty[0] as TextLayer).content.text).toBe('Untitled');
+
+    const present = resolveTokens([textLayer('a', '{title|Untitled}')], block({ title: 'Real' }));
+    expect((present[0] as TextLayer).content.text).toBe('Real');
+  });
+
+  it('uses the default on a missing {attr:key|…}', () => {
+    const layers = resolveTokens(
+      [textLayer('a', '{attr:subtitle|Untitled}')],
+      block({ templateOverrides: {} }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('Untitled');
+  });
+
+  it('uses the image-src default (and keeps the layer) when the image index is out of range', () => {
+    const layers = resolveTokens([imageLayer('a', '{image:1|fallback.jpg}')], block());
+    expect(layers).toHaveLength(1);
+    expect((layers[0] as ImageLayer).content.src).toBe('fallback.jpg');
+  });
+
+  it('still drops the image layer when {image:N} misses and no default is given', () => {
+    const layers = resolveTokens([imageLayer('a', '{image:1}')], block());
+    expect(layers).toHaveLength(0);
+  });
+
+  it('an empty default renders as empty (present token collapses to blank)', () => {
+    const layers = resolveTokens([textLayer('a', '[{attr:x|}]')], block());
+    expect((layers[0] as TextLayer).content.text).toBe('[]');
+  });
+});
+
+describe('resolveTokens — escape vs pipe defaults', () => {
+  it('leaves {{title|Untitled}} literal (escape shields the pipe default too)', () => {
+    const layers = resolveTokens(
+      [textLayer('a', 'Token: {{title|Untitled}}')],
+      block({ title: 'Real' }),
+    );
+    expect((layers[0] as TextLayer).content.text).toBe('Token: {title|Untitled}');
+  });
+});
+
+function repeatText(
+  id: string,
+  text: string,
+  repeat: CustomTemplateLayer['repeat'],
+): CustomTemplateLayer {
+  return {
+    id,
+    type: 'text',
+    position: { x: '0%', y: '10%', width: '30%', height: '20%' },
+    content: { text, style: { fontSize: 24, color: '#000' } },
+    repeat,
+  };
+}
+
+const imagesBlock = block({
+  contents: [
+    {
+      type: 'paragraph',
+      children: [
+        { type: 'image', url: '/one.png', alt: 'One' },
+        { type: 'image', url: '/two.png', alt: 'Two' },
+        { type: 'image', url: '/three.png', alt: 'Three' },
+      ],
+    },
+  ],
+});
+
+describe('resolveTokens — repeat', () => {
+  it('clones a layer once per image and resolves per-item tokens', () => {
+    const layers = resolveTokens(
+      [repeatText('cap', '{index}. {item} ({item:src})', { source: 'images' })],
+      imagesBlock,
+    );
+    expect(layers).toHaveLength(3);
+    expect((layers[0] as TextLayer).content.text).toBe('1. One (/one.png)');
+    expect((layers[1] as TextLayer).content.text).toBe('2. Two (/two.png)');
+    expect((layers[2] as TextLayer).content.text).toBe('3. Three (/three.png)');
+  });
+
+  it('gives each clone a unique id and strips the repeat prop', () => {
+    const layers = resolveTokens([repeatText('cap', '{item}', { source: 'images' })], imagesBlock);
+    expect(layers.map((l) => l.id)).toEqual(['cap-0', 'cap-1', 'cap-2']);
+    expect(layers.every((l) => !('repeat' in l))).toBe(true);
+  });
+
+  it('iterates children titles', () => {
+    const layers = resolveTokens(
+      [repeatText('c', '{index}:{item}', { source: 'children' })],
+      block({ children: [block({ id: 'a', title: 'Alpha' }), block({ id: 'b', title: 'Beta' })] }),
+    );
+    expect(layers.map((l) => (l as TextLayer).content.text)).toEqual(['1:Alpha', '2:Beta']);
+  });
+
+  it('iterates list items', () => {
+    const layers = resolveTokens(
+      [repeatText('li', '- {item}', { source: 'listItems' })],
+      block({
+        contents: [
+          {
+            type: 'list',
+            ordered: false,
+            children: [
+              {
+                type: 'listItem',
+                children: [{ type: 'paragraph', children: [{ type: 'text', value: 'First' }] }],
+              },
+              {
+                type: 'listItem',
+                children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Second' }] }],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(layers.map((l) => (l as TextLayer).content.text)).toEqual(['- First', '- Second']);
+  });
+
+  it('caps the number of clones at max', () => {
+    const layers = resolveTokens(
+      [repeatText('cap', '{item}', { source: 'images', max: 2 })],
+      imagesBlock,
+    );
+    expect(layers).toHaveLength(2);
+    expect(layers.map((l) => (l as TextLayer).content.text)).toEqual(['One', 'Two']);
+  });
+
+  it('offsets position.y in column direction by height + gap', () => {
+    const layers = resolveTokens(
+      [repeatText('cap', '{item}', { source: 'images', direction: 'column', gap: 4 })],
+      imagesBlock,
+    );
+    // base y = 10%, height = 20%, gap = 4 → cursor advances by 24 each item
+    expect(layers.map((l) => l.position.y)).toEqual(['10%', '34%', '58%']);
+    // x is untouched in column direction
+    expect(layers.every((l) => l.position.x === '0%')).toBe(true);
+  });
+
+  it('offsets position.x in row direction by width + gap', () => {
+    const layers = resolveTokens(
+      [repeatText('cap', '{item}', { source: 'images', direction: 'row', gap: 10 })],
+      imagesBlock,
+    );
+    // base x = 0%, width = 30%, gap = 10 → cursor advances by 40 each item
+    expect(layers.map((l) => l.position.x)).toEqual(['0%', '40%', '80%']);
+    expect(layers.every((l) => l.position.y === '10%')).toBe(true);
+  });
+
+  it('renders nothing when the source collection is empty', () => {
+    const layers = resolveTokens([repeatText('cap', '{item}', { source: 'images' })], block());
+    expect(layers).toHaveLength(0);
+  });
+
+  it('resolves {item:src} in an image layer inside a repeat', () => {
+    const imgRepeat: CustomTemplateLayer = {
+      id: 'img',
+      type: 'image',
+      position: { x: '0%', y: '0%', width: '25%', height: '25%' },
+      content: { src: '{item:src}', alt: '{item:label}' },
+      repeat: { source: 'images', direction: 'row', gap: 0 },
+    };
+    const layers = resolveTokens([imgRepeat], imagesBlock);
+    expect(layers).toHaveLength(3);
+    expect((layers[0] as ImageLayer).content.src).toBe('/one.png');
+    expect((layers[0] as ImageLayer).content.alt).toBe('One');
+    expect((layers[2] as ImageLayer).content.src).toBe('/three.png');
+  });
+});
+
+describe('resolveTokens — {item}/{index} outside a repeat', () => {
+  it('leaves per-item tokens literal when there is no repeat context', () => {
+    const layers = resolveTokens([textLayer('a', '{item} {index}')], block());
+    expect((layers[0] as TextLayer).content.text).toBe('{item} {index}');
+  });
+});
+
+describe('collectListItems', () => {
+  it('returns top-level list-item text and skips nested double-counting', () => {
+    const b = block({
+      contents: [
+        {
+          type: 'list',
+          ordered: false,
+          children: [
+            {
+              type: 'listItem',
+              children: [
+                { type: 'paragraph', children: [{ type: 'text', value: 'Parent' }] },
+                {
+                  type: 'list',
+                  ordered: false,
+                  children: [
+                    {
+                      type: 'listItem',
+                      children: [
+                        { type: 'paragraph', children: [{ type: 'text', value: 'Nested' }] },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              type: 'listItem',
+              children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Sibling' }] }],
+            },
+          ],
+        },
+      ],
+    });
+    // Only two top-level items; the nested item is folded into "Parent Nested".
+    expect(collectListItems(b)).toEqual(['Parent Nested', 'Sibling']);
+  });
+
+  it('returns [] when the block has no list content', () => {
+    expect(collectListItems(block())).toEqual([]);
+  });
+});

package/src/doc/templates/videoWithCaption.ts

@@ -35,9 +35,9 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
     videoLicense,
   } = input;
   const caption = rawCaption ? cleanCaption(rawCaption) : rawCaption;
-  const { theme, layout } = context;
+  const { theme } = context;
 
-  const captionFontSize = themedFontSize(36, context, false);
+  const captionFontSize = themedFontSize(30, context, false);
   const creditFontSize = themedFontSize(16, context, false);
 
   const layers: Layer[] = [
@@ -60,31 +60,30 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
     },
   ];
 
-  // Caption text at bottom with gradient for readability. The scrim is
-  // tinted from the theme background so the theme text color on top of it
-  // stays readable in light and dark themes alike; it fades toward the
-  // frame edge the caption sits on.
+  // 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 scrimAngle = captionPosition === 'top' ? 180 : 0;
+    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(${scrimAngle}deg, ${withAlpha(bg, 0.8)} 0%, ${withAlpha(bg, 0.35)} 60%, ${withAlpha(bg, 0)} 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',
@@ -96,13 +95,15 @@ export function videoWithCaption(input: VideoWithCaptionInput, context: Template
           color: theme.colors.text,
           textAlign: 'center',
           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 },
     });

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

package/src/doc/utils/shapeGeometry.ts

@@ -9,9 +9,11 @@
  *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
  *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
  *    editor's edge renderer).
- *  - `connectorPath(routing, start, end)` + `clipEndpoints(a, b)` → the line/edge
+ *  - `connectorPath(routing, start, end)` + `snapEndpoints(a, b)` → the line/edge
  *    geometry between two shapes (straight / orthogonal / curved), lifted from the
- *    diagram template so drawings and diagrams draw identical connectors.
+ *    diagram template so drawings and diagrams draw identical connectors. The older
+ *    `clipEndpoints(a, b)` helper remains for free-angle clipping, but rendered
+ *    connectors use snapped ports so authored lines land on stable attachment points.
  */
 
 import type { MarkerStyle } from '../../schemas/Doc.js';
@@ -411,6 +413,22 @@ export interface ClipBox {
   ry: number;
 }
 
+export type ConnectorPort =
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-right'
+  | 'bottom-left';
+
+export interface ConnectorSnapPoint {
+  port: ConnectorPort;
+  x: number;
+  y: number;
+}
+
 /** Intersection of the center-to-center line with `from`'s bounding box. */
 export function clipPoint(from: ClipBox, to: ClipBox): { x: number; y: number } {
   const dx = to.cx - from.cx;
@@ -430,6 +448,76 @@ export function clipEndpoints(
   return { start: clipPoint(a, b), end: clipPoint(b, a) };
 }
 
+/** The stable connector ports exposed around a shape/card box. */
+export function snapPoints(box: ClipBox): ConnectorSnapPoint[] {
+  const left = box.cx - box.rx;
+  const right = box.cx + box.rx;
+  const top = box.cy - box.ry;
+  const bottom = box.cy + box.ry;
+  return [
+    { port: 'top', x: box.cx, y: top },
+    { port: 'right', x: right, y: box.cy },
+    { port: 'bottom', x: box.cx, y: bottom },
+    { port: 'left', x: left, y: box.cy },
+    { port: 'top-left', x: left, y: top },
+    { port: 'top-right', x: right, y: top },
+    { port: 'bottom-right', x: right, y: bottom },
+    { port: 'bottom-left', x: left, y: bottom },
+  ];
+}
+
+/** Nearest stable connector port on `box` to an arbitrary point. */
+export function nearestSnapPoint(
+  box: ClipBox,
+  point: { x: number; y: number },
+): ConnectorSnapPoint {
+  let best = snapPoints(box)[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of snapPoints(box)) {
+    const score = distanceSq(candidate, point) + portTieBreak(candidate.port);
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/**
+ * Pick the pair of connector ports, one on each box, with the shortest
+ * distance between them. This gives stable attachments to side/corner handles
+ * instead of arbitrary center-ray intersections.
+ */
+export function snapEndpoints(
+  a: ClipBox,
+  b: ClipBox,
+): { start: ConnectorSnapPoint; end: ConnectorSnapPoint } {
+  let bestStart = snapPoints(a)[0];
+  let bestEnd = snapPoints(b)[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const start of snapPoints(a)) {
+    for (const end of snapPoints(b)) {
+      const score = distanceSq(start, end) + portTieBreak(start.port) + portTieBreak(end.port);
+      if (score < bestScore) {
+        bestStart = start;
+        bestEnd = end;
+        bestScore = score;
+      }
+    }
+  }
+  return { start: bestStart, end: bestEnd };
+}
+
+function distanceSq(a: { x: number; y: number }, b: { x: number; y: number }): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return dx * dx + dy * dy;
+}
+
+function portTieBreak(port: ConnectorPort): number {
+  return port.includes('-') ? 0.02 : 0;
+}
+
 /** Build the SVG `d` for a connector between two clipped endpoints. */
 export function connectorPath(
   routing: ConnectorRouting,