@bendyline/squisq 1.4.1 → 1.5.1

package/src/__tests__/mediaAnnotations.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { markdownToDoc } from '../doc/markdownToDoc.js';
+import { resolveMediaSchedule } from '../schemas/Media.js';
+
+function toDoc(md: string) {
+  return markdownToDoc(parseMarkdown(md), { articleId: 't' });
+}
+
+describe('markdownToDoc media annotations', () => {
+  it('lifts a block-level audio annotation into block.media', () => {
+    const doc = toDoc(
+      '# One {duration=10}\n\nIntro.\n\n{[audio src=narration.mp3 startAt=5 clipEnd=8 spillover=true]}\n',
+    );
+    const block = doc.blocks[0];
+    expect(block.media).toHaveLength(1);
+    expect(block.media![0]).toMatchObject({
+      src: 'narration.mp3',
+      kind: 'audio',
+      startAt: 5,
+      clipEnd: 8,
+      spillover: true,
+      anchor: 'block',
+    });
+    // The annotation paragraph is removed from the visible contents.
+    expect(JSON.stringify(block.contents)).not.toContain('narration.mp3');
+  });
+
+  it('routes anchor=document annotations to doc.documentMedia', () => {
+    const doc = toDoc('{[audio src=voice.mp3 anchor=document]}\n\n# First\n\nBody.\n');
+    expect(doc.documentMedia).toHaveLength(1);
+    expect(doc.documentMedia![0]).toMatchObject({ src: 'voice.mp3', anchor: 'document' });
+    // It is not also attached to the preamble block's media.
+    expect(doc.blocks[0].media).toBeUndefined();
+  });
+
+  it('recognizes a video annotation as kind video', () => {
+    const doc = toDoc('# B {duration=20}\n\n{[video src=clip.mp4 clipStart=2 clipEnd=8]}\n');
+    expect(doc.blocks[0].media![0]).toMatchObject({
+      src: 'clip.mp4',
+      kind: 'video',
+      clipStart: 2,
+      clipEnd: 8,
+    });
+  });
+
+  it('accepts startTime as an alias of startAt (startAt wins when both given)', () => {
+    const alias = toDoc('# B {duration=20}\n\n{[audio src=a.mp3 startTime=5]}\n');
+    expect(alias.blocks[0].media![0].startAt).toBe(5);
+
+    const both = toDoc('# B {duration=20}\n\n{[audio src=a.mp3 startAt=3 startTime=5]}\n');
+    expect(both.blocks[0].media![0].startAt).toBe(3);
+  });
+
+  it('media annotation text does not inflate block duration', () => {
+    // No explicit duration; body is only the annotation → default (5s), not reading-time of the annotation text.
+    const doc = toDoc('# B\n\n{[audio src=a.mp3]}\n');
+    expect(doc.blocks[0].duration).toBe(5);
+  });
+
+  it('feeds resolveMediaSchedule end to end', () => {
+    const doc = toDoc(
+      '{[audio src=voice.mp3 anchor=document]}\n\n# One {duration=30}\n\n# Two {duration=20}\n\n{[audio src=a.mp3 startAt=5 clipEnd=8]}\n',
+    );
+    const sched = resolveMediaSchedule(doc);
+    const doc1 = sched.find((c) => c.anchor === 'document')!;
+    const block = sched.find((c) => c.anchor === 'block')!;
+    expect(doc1.absoluteStart).toBe(0);
+    expect(doc1.absoluteEnd).toBe(50); // spans both blocks
+    expect(block.absoluteStart).toBe(35); // block Two at 30 + startAt 5
+  });
+});
+
+describe('media annotations vs standalone template blocks', () => {
+  it('extracts media annotations as clips, not standalone blocks (media names win)', () => {
+    const doc = toDoc('# One\n\nIntro.\n\n{[audio src=narration.mp3]}\n\n{[video src=clip.mp4]}\n');
+    const block = doc.blocks[0];
+    expect(block.media?.map((m) => m.kind)).toEqual(['audio', 'video']);
+    // No sibling standalone blocks were produced for the media names.
+    expect(doc.blocks).toHaveLength(1);
+    expect(doc.blocks.some((b) => b.standaloneAnnotation)).toBe(false);
+  });
+
+  it('mixes a media clip and a standalone template block in one section', () => {
+    const doc = toDoc('# One\n\n{[audio src=n.mp3]}\n\n{[quote]}\n\nquoted\n');
+    expect(doc.blocks[0].media?.map((m) => m.kind)).toEqual(['audio']);
+    const q = doc.blocks[1];
+    expect(q.template).toBe('quote');
+    expect(q.standaloneAnnotation).toBe(true);
+  });
+});

package/src/__tests__/mediaSchedule.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { resolveMediaSchedule, getDocPlaybackDuration } from '../schemas/Media.js';
+import type { Doc, Block } from '../schemas/Doc.js';
+
+function block(partial: Partial<Block>): Block {
+  return {
+    id: partial.id ?? 'b',
+    startTime: partial.startTime ?? 0,
+    duration: partial.duration ?? 10,
+    audioSegment: 0,
+    ...partial,
+  };
+}
+
+function doc(blocks: Block[], extra?: Partial<Doc>): Doc {
+  const lastEnd = blocks.reduce((m, b) => Math.max(m, b.startTime + b.duration), 0);
+  return { articleId: 't', duration: lastEnd, blocks, audio: { segments: [] }, ...extra };
+}
+
+describe('resolveMediaSchedule', () => {
+  it('offsets a block clip by startAt relative to the block start', () => {
+    // Block #2 starts at 30s; a clip with startAt=5 plays at 35s.
+    const d = doc([
+      block({ id: 'one', startTime: 0, duration: 30 }),
+      block({
+        id: 'two',
+        startTime: 30,
+        duration: 20,
+        media: [{ id: 'm1', src: 'a.mp3', kind: 'audio', startAt: 5, clipEnd: 8, anchor: 'block' }],
+      }),
+    ]);
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteStart).toBe(35);
+    expect(clip.absoluteEnd).toBe(43); // 35 + (clipEnd 8 - clipStart 0)
+    expect(clip.sourceIn).toBe(0);
+    expect(clip.blockId).toBe('two');
+  });
+
+  it('clamps a non-spillover clip to the block end', () => {
+    const d = doc([
+      block({
+        id: 'b',
+        startTime: 0,
+        duration: 10,
+        media: [
+          { id: 'm', src: 'a.mp3', kind: 'audio', startAt: 2, clipEnd: 100, anchor: 'block' },
+        ],
+      }),
+    ]);
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteEnd).toBe(10); // clamped to block end, not 2 + 100
+  });
+
+  it('lets a spillover clip run past the block end', () => {
+    const d = doc([
+      block({
+        id: 'b',
+        startTime: 0,
+        duration: 10,
+        media: [
+          {
+            id: 'm',
+            src: 'a.mp3',
+            kind: 'audio',
+            startAt: 2,
+            clipEnd: 100,
+            spillover: true,
+            anchor: 'block',
+          },
+        ],
+      }),
+      block({ id: 'b2', startTime: 10, duration: 10 }),
+    ]);
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteEnd).toBe(102); // 2 + 100, past the block end
+  });
+
+  it('spans the whole document for an anchor=document clip', () => {
+    const d = doc([block({ id: 'b', startTime: 0, duration: 40 })], {
+      documentMedia: [
+        { id: 'narr', src: 'voice.mp3', kind: 'audio', startAt: 0, anchor: 'document' },
+      ],
+    });
+    const [clip] = resolveMediaSchedule(d);
+    expect(clip.absoluteStart).toBe(0);
+    expect(clip.absoluteEnd).toBe(40);
+    expect(clip.anchor).toBe('document');
+  });
+});
+
+describe('getDocPlaybackDuration', () => {
+  it('extends total duration to include media spillover', () => {
+    const d = doc([
+      block({
+        id: 'b',
+        startTime: 0,
+        duration: 10,
+        media: [
+          {
+            id: 'm',
+            src: 'a.mp3',
+            kind: 'audio',
+            startAt: 0,
+            clipEnd: 25,
+            spillover: true,
+            anchor: 'block',
+          },
+        ],
+      }),
+    ]);
+    expect(getDocPlaybackDuration(d)).toBe(25);
+  });
+
+  it('falls back to the block timeline when there is no media', () => {
+    const d = doc([block({ id: 'b', startTime: 0, duration: 12 })]);
+    expect(getDocPlaybackDuration(d)).toBe(12);
+  });
+});

package/src/__tests__/pandocAttrParse.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown, stringifyMarkdown } from '../markdown/index.js';
+
+function getHeading(md: string) {
+  const doc = parseMarkdown(md);
+  const heading = doc.children[0];
+  if (heading.type !== 'heading') throw new Error('expected heading');
+  return heading;
+}
+
+describe('Pandoc heading attribute parse', () => {
+  it('extracts an id-only block', () => {
+    const h = getHeading('## Section title {#intro}');
+    expect(h.attributes).toEqual({ id: 'intro' });
+    expect(h.templateAnnotation).toBeUndefined();
+  });
+
+  it('extracts classes', () => {
+    const h = getHeading('## X {.alpha .beta}');
+    expect(h.attributes?.classes).toEqual(['alpha', 'beta']);
+  });
+
+  it('extracts id + classes + params', () => {
+    const h = getHeading('## X {#abc .v1 .v2 x=400 y=200}');
+    expect(h.attributes?.id).toBe('abc');
+    expect(h.attributes?.classes).toEqual(['v1', 'v2']);
+    expect(h.attributes?.params).toEqual({ x: '400', y: '200' });
+    expect(h.attributes?.blockMeta).toEqual({ x: 400, y: 200 });
+  });
+
+  it('coerces connectsTo to a typed list', () => {
+    const h = getHeading('## X {connectsTo=foo:veryImportant,bar:requires,baz:requires}');
+    expect(h.attributes?.blockMeta?.connectsTo).toEqual([
+      { target: 'foo', type: 'veryImportant' },
+      { target: 'bar', type: 'requires' },
+      { target: 'baz', type: 'requires' },
+    ]);
+  });
+
+  it('coerces startTime/duration to seconds', () => {
+    const h = getHeading('## X {startTime=01:30 duration=00:45}');
+    expect(h.attributes?.blockMeta?.startTime).toBe(90);
+    expect(h.attributes?.blockMeta?.duration).toBe(45);
+  });
+
+  it('routes unknown keys to metadata', () => {
+    const h = getHeading('## X {#a priority=high level=info}');
+    expect(h.attributes?.metadata).toEqual({ priority: 'high', level: 'info' });
+    expect(h.attributes?.blockMeta).toBeUndefined();
+  });
+
+  it('handles quoted values with spaces', () => {
+    const h = getHeading('## X {caption="hello world"}');
+    expect(h.attributes?.params).toEqual({ caption: 'hello world' });
+    expect(h.attributes?.metadata).toEqual({ caption: 'hello world' });
+  });
+
+  it('preserves commas inside quoted values', () => {
+    const h = getHeading('## X {caption="hello, friend"}');
+    expect(h.attributes?.metadata).toEqual({ caption: 'hello, friend' });
+  });
+
+  it('escaped quotes inside quoted values', () => {
+    const h = getHeading('## X {label="he said \\"hi\\""}');
+    expect(h.attributes?.metadata?.label).toBe('he said "hi"');
+  });
+
+  it('handles single-quoted values with spaces', () => {
+    const h = getHeading("## X {caption='hello world'}");
+    expect(h.attributes?.params).toEqual({ caption: 'hello world' });
+  });
+
+  it('allows } inside a quoted value', () => {
+    const h = getHeading('## X {caption="a } b"}');
+    expect(h.attributes?.params).toEqual({ caption: 'a } b' });
+  });
+
+  it('treats an apostrophe inside an unquoted value as literal', () => {
+    const h = getHeading("## X {name=O'Brien x=4}");
+    expect(h.attributes?.metadata).toEqual({ name: "O'Brien" });
+    expect(h.attributes?.blockMeta?.x).toBe(4);
+  });
+
+  it('duplicate id: last wins', () => {
+    const h = getHeading('## X {#a #b}');
+    expect(h.attributes?.id).toBe('b');
+  });
+
+  it('duplicate key: last wins', () => {
+    const h = getHeading('## X {x=1 x=2}');
+    expect(h.attributes?.blockMeta?.x).toBe(2);
+  });
+
+  it('does NOT match a non-trailing brace block', () => {
+    const h = getHeading('## The {#wrong} section');
+    expect(h.attributes).toBeUndefined();
+  });
+
+  it('does NOT collide with {[…]} template annotation', () => {
+    const h = getHeading('## X {[chart]}');
+    expect(h.templateAnnotation).toEqual({ template: 'chart' });
+    expect(h.attributes).toBeUndefined();
+  });
+});
+
+describe('Coexistence of {#…} and {[…]}', () => {
+  it('Pandoc first, then template', () => {
+    const h = getHeading('## X {#abc} {[chart]}');
+    expect(h.attributes?.id).toBe('abc');
+    expect(h.templateAnnotation?.template).toBe('chart');
+  });
+
+  it('Template first, then Pandoc (order-agnostic)', () => {
+    const h = getHeading('## X {[chart]} {#abc}');
+    expect(h.attributes?.id).toBe('abc');
+    expect(h.templateAnnotation?.template).toBe('chart');
+  });
+
+  it('both with params on each side', () => {
+    const h = getHeading('## X {#a x=400 y=200} {[chart colorScheme=blue]}');
+    expect(h.attributes?.id).toBe('a');
+    expect(h.attributes?.blockMeta?.x).toBe(400);
+    expect(h.attributes?.blockMeta?.y).toBe(200);
+    expect(h.templateAnnotation?.template).toBe('chart');
+    expect(h.templateAnnotation?.params).toEqual({ colorScheme: 'blue' });
+  });
+
+  it('Pandoc block-meta does not leak into templateOverrides', () => {
+    const h = getHeading('## X {#a x=400} {[chart colorScheme=blue]}');
+    expect(h.templateAnnotation?.params).toEqual({ colorScheme: 'blue' });
+    expect(h.attributes?.params).toEqual({ x: '400' });
+  });
+});
+
+describe('Markdown round-trip with attributes', () => {
+  it('Pandoc-only id round-trips', () => {
+    const src = '## Section title {#intro}\n';
+    const md = parseMarkdown(src);
+    expect(stringifyMarkdown(md).trim()).toBe(src.trim());
+  });
+
+  it('canonicalizes order: Pandoc first, then template', () => {
+    const input = '## X {[chart]} {#abc}\n';
+    const md = parseMarkdown(input);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe('## X {#abc} {[chart]}');
+  });
+
+  it('full attribute set round-trips', () => {
+    const src =
+      '## Architecture {#arch x=600 y=300 connectsTo=foo:veryImportant,bar:requires,baz:requires} {[diagramNode]}\n';
+    const md = parseMarkdown(src);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe(src.trim());
+  });
+
+  it('quoted value round-trips with quoting preserved', () => {
+    const src = '## X {caption="hello world"}\n';
+    const md = parseMarkdown(src);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe(src.trim());
+  });
+
+  it('existing {[…]}-only docs are unchanged', () => {
+    const src = '## Getting Started {[chart colorScheme=blue]}\n';
+    const md = parseMarkdown(src);
+    const out = stringifyMarkdown(md).trim();
+    expect(out).toBe(src.trim());
+  });
+
+  it('single-quoted values canonicalize to double quotes', () => {
+    const md = parseMarkdown("## X {caption='hello world'}");
+    expect(stringifyMarkdown(md).trim()).toBe('## X {caption="hello world"}');
+  });
+
+  it('a value containing a double quote round-trips via single quotes', () => {
+    const src = '## X {label=\'say "hi"\'}';
+    const md = parseMarkdown(src);
+    expect(stringifyMarkdown(md).trim()).toBe(src);
+  });
+
+  it('a quoted } round-trips', () => {
+    const src = '## X {caption="a } b"}';
+    const md = parseMarkdown(src);
+    expect(stringifyMarkdown(md).trim()).toBe(src);
+  });
+});

package/src/__tests__/resolveDocTheme.test.ts

@@ -0,0 +1,55 @@
+/**
+ * resolveThemeForDoc — pure, doc-scoped theme resolution.
+ *
+ * The theme analog of buildRegistry: an inline custom theme resolves from the
+ * doc's own `customThemes` list, with no global `registerTheme` call. Falls
+ * back to built-ins for non-inline ids.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveThemeForDoc } from '../doc/resolveDocTheme';
+import { compileTheme } from '../schemas/themeCompile';
+import { DEFAULT_THEME } from '../schemas/themeLibrary';
+import type { Doc } from '../schemas/Doc.js';
+
+const brand = compileTheme({
+  id: 'my-brand',
+  name: 'My Brand',
+  seedColors: { primary: '#3182ce' },
+});
+
+function docWith(partial: Partial<Doc>): Doc {
+  return {
+    articleId: 'd',
+    duration: 0,
+    blocks: [],
+    audio: { segments: [] },
+    ...partial,
+  } as Doc;
+}
+
+describe('resolveThemeForDoc', () => {
+  it('resolves an inline custom theme doc-scoped (no global registration)', () => {
+    const doc = docWith({ customThemes: [brand], frontmatter: { 'squisq-theme': 'my-brand' } });
+    expect(resolveThemeForDoc(doc)).toEqual(brand);
+  });
+
+  it('honors an explicit id over the frontmatter selection', () => {
+    const doc = docWith({ customThemes: [brand], frontmatter: { 'squisq-theme': 'cinematic' } });
+    expect(resolveThemeForDoc(doc, 'my-brand')).toEqual(brand);
+  });
+
+  it('falls back to a built-in when the id is not an inline theme', () => {
+    const doc = docWith({ customThemes: [brand], frontmatter: { 'squisq-theme': 'cinematic' } });
+    expect(resolveThemeForDoc(doc).id).toBe('cinematic');
+  });
+
+  it('uses Doc.themeId when there is no explicit or frontmatter id', () => {
+    const doc = docWith({ customThemes: [brand], themeId: 'my-brand' });
+    expect(resolveThemeForDoc(doc)).toEqual(brand);
+  });
+
+  it('returns the default theme for a null doc', () => {
+    expect(resolveThemeForDoc(null).id).toBe(DEFAULT_THEME.id);
+  });
+});

package/src/__tests__/rootExports.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import * as root from '../index';
+import * as icons from '../icons/index';
+import * as transform from '../transform/index';
+
+const transformRuntimeExports = [
+  'applyTransform',
+  'resolveTransformStyle',
+  'getTransformStyleIds',
+  'getTransformStyleSummaries',
+  'DEFAULT_TRANSFORM_STYLE_ID',
+  'analyzeBlocks',
+  'extractDocImages',
+] as const;
+
+const iconRuntimeExports = [
+  'ICONS',
+  'resolveIcon',
+  'canonicalIconToken',
+  'looksLikeIconToken',
+  'suggestIcons',
+  'iconGlyph',
+] as const;
+
+function expectReExported(
+  rootExports: Record<string, unknown>,
+  subpathExports: Record<string, unknown>,
+  names: readonly string[],
+): void {
+  for (const name of names) {
+    expect(rootExports[name], `root barrel should re-export ${name}`).toBe(subpathExports[name]);
+  }
+}
+
+describe('root barrel exports', () => {
+  it('re-exports transform runtime APIs', () => {
+    expectReExported(root, transform, transformRuntimeExports);
+  });
+
+  it('re-exports icon runtime APIs', () => {
+    expectReExported(root, icons, iconRuntimeExports);
+  });
+});

package/src/__tests__/shapeGeometry.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import {
+  shapePath,
+  markerPath,
+  connectorPath,
+  clipEndpoints,
+  lineStyleDasharray,
+  PATH_SHAPE_KINDS,
+} from '../doc/utils/shapeGeometry.js';
+
+describe('shapePath', () => {
+  it('returns a non-empty path beginning with M for every path-shape kind', () => {
+    for (const kind of PATH_SHAPE_KINDS) {
+      const d = shapePath(kind, 0, 0, 100, 80);
+      expect(d, kind).toBeTruthy();
+      expect(d?.startsWith('M'), kind).toBe(true);
+    }
+  });
+
+  it('returns null for natively-rendered primitives', () => {
+    for (const kind of ['rect', 'circle', 'line', 'text', 'path', 'arrow']) {
+      expect(shapePath(kind, 0, 0, 10, 10), kind).toBeNull();
+    }
+  });
+
+  it('triangle is a closed 3-point polygon inscribed in the box', () => {
+    expect(shapePath('triangle', 0, 0, 100, 100)).toBe('M 50 0 L 100 100 L 0 100 Z');
+  });
+
+  it('diamond hits the four edge midpoints', () => {
+    expect(shapePath('diamond', 0, 0, 100, 100)).toBe('M 50 0 L 100 50 L 50 100 L 0 50 Z');
+  });
+
+  it('honors the bounding-box offset', () => {
+    expect(shapePath('triangle', 10, 20, 100, 100)).toBe('M 60 20 L 110 120 L 10 120 Z');
+  });
+});
+
+describe('markerPath', () => {
+  it('arrow end is a filled triangle; none is null', () => {
+    expect(markerPath('arrow', 'end')).toEqual({ d: 'M 0 0 L 10 5 L 0 10 z', filled: true });
+    expect(markerPath('none', 'end')).toBeNull();
+  });
+
+  it('open is unfilled; diamond/circle/square are filled', () => {
+    expect(markerPath('open', 'end')?.filled).toBe(false);
+    expect(markerPath('diamond', 'end')?.filled).toBe(true);
+    expect(markerPath('circle', 'end')?.filled).toBe(true);
+    expect(markerPath('square', 'end')?.filled).toBe(true);
+  });
+
+  it('start mirrors the arrow horizontally', () => {
+    expect(markerPath('arrow', 'start')).toEqual({ d: 'M 10 0 L 0 5 L 10 10 z', filled: true });
+  });
+});
+
+describe('connectorPath', () => {
+  const a = { x: 0, y: 0 };
+  const b = { x: 100, y: 50 };
+
+  it('straight is a single line segment', () => {
+    expect(connectorPath('straight', a, b)).toBe('M 0 0 L 100 50');
+  });
+
+  it('orthogonal has a mid elbow', () => {
+    expect(connectorPath('orthogonal', a, b)).toBe('M 0 0 L 50 0 L 50 50 L 100 50');
+  });
+
+  it('curved is a cubic bezier', () => {
+    expect(connectorPath('curved', a, b).startsWith('M 0 0 C')).toBe(true);
+  });
+});
+
+describe('clipEndpoints', () => {
+  it('clips both endpoints to the box edges', () => {
+    const r = clipEndpoints({ cx: 0, cy: 0, rx: 10, ry: 10 }, { cx: 100, cy: 0, rx: 10, ry: 10 });
+    expect(r.start).toEqual({ x: 10, y: 0 });
+    expect(r.end).toEqual({ x: 90, y: 0 });
+  });
+});
+
+describe('lineStyleDasharray', () => {
+  it('maps line styles to dash patterns', () => {
+    expect(lineStyleDasharray('dashed')).toBe('8 6');
+    expect(lineStyleDasharray('dotted')).toBe('2 6');
+    expect(lineStyleDasharray('solid')).toBeUndefined();
+    expect(lineStyleDasharray(undefined)).toBeUndefined();
+  });
+});