@bendyline/squisq 1.4.0 → 1.5.0

package/src/__tests__/annotationCoercion.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from 'vitest';
+import {
+  coerceAnnotationValues,
+  parseTimeSeconds,
+  parseConnectionList,
+  KNOWN_BLOCK_META_KEYS,
+  BLOCK_META_KEY_DESCRIPTORS,
+} from '../markdown/annotationCoercion.js';
+import { TRANSITION_TYPES, TRANSITION_DIRECTIONS } from '../schemas/Transitions.js';
+
+describe('parseTimeSeconds', () => {
+  it('accepts bare seconds (integer)', () => {
+    expect(parseTimeSeconds('5')).toBe(5);
+  });
+
+  it('accepts bare seconds (decimal)', () => {
+    expect(parseTimeSeconds('5.5')).toBe(5.5);
+  });
+
+  it('accepts mm:ss', () => {
+    expect(parseTimeSeconds('01:30')).toBe(90);
+    expect(parseTimeSeconds('0:05')).toBe(5);
+    expect(parseTimeSeconds('10:00')).toBe(600);
+  });
+
+  it('accepts mm:ss.ms (fractional seconds)', () => {
+    expect(parseTimeSeconds('01:30.500')).toBeCloseTo(90.5, 6);
+    expect(parseTimeSeconds('02:30.5')).toBeCloseTo(150.5, 6);
+  });
+
+  it('accepts Nms (milliseconds)', () => {
+    expect(parseTimeSeconds('1500ms')).toBe(1.5);
+    expect(parseTimeSeconds('0ms')).toBe(0);
+  });
+
+  it('trims leading/trailing whitespace', () => {
+    expect(parseTimeSeconds('  90  ')).toBe(90);
+  });
+
+  it('rejects malformed input', () => {
+    expect(parseTimeSeconds('not-a-time')).toBeNull();
+    expect(parseTimeSeconds('99:bad')).toBeNull();
+    expect(parseTimeSeconds('')).toBeNull();
+    expect(parseTimeSeconds('  ')).toBeNull();
+  });
+
+  it('rejects seconds field >= 60', () => {
+    expect(parseTimeSeconds('1:60')).toBeNull();
+    expect(parseTimeSeconds('1:75')).toBeNull();
+  });
+});
+
+describe('parseConnectionList', () => {
+  it('parses a single bare target', () => {
+    expect(parseConnectionList('foo')).toEqual({
+      list: [{ target: 'foo' }],
+      warning: null,
+    });
+  });
+
+  it('parses target:type pairs', () => {
+    expect(parseConnectionList('foo:flow')).toEqual({
+      list: [{ target: 'foo', type: 'flow' }],
+      warning: null,
+    });
+  });
+
+  it('parses mixed bare + typed entries', () => {
+    expect(parseConnectionList('foo:veryImportant,bar:requires,baz:requires')).toEqual({
+      list: [
+        { target: 'foo', type: 'veryImportant' },
+        { target: 'bar', type: 'requires' },
+        { target: 'baz', type: 'requires' },
+      ],
+      warning: null,
+    });
+  });
+
+  it('trims whitespace around items', () => {
+    expect(parseConnectionList('foo, bar:flow , baz').list).toEqual([
+      { target: 'foo' },
+      { target: 'bar', type: 'flow' },
+      { target: 'baz' },
+    ]);
+  });
+
+  it('returns empty list for empty input', () => {
+    expect(parseConnectionList('')).toEqual({ list: [], warning: null });
+    expect(parseConnectionList('   ')).toEqual({ list: [], warning: null });
+  });
+
+  it('filters empty segments and warns', () => {
+    const result = parseConnectionList('a,,b');
+    expect(result.list).toEqual([{ target: 'a' }, { target: 'b' }]);
+    expect(result.warning).toContain('empty');
+  });
+
+  it('drops entries with empty target before colon', () => {
+    const result = parseConnectionList(':flow,foo');
+    expect(result.list).toEqual([{ target: 'foo' }]);
+    expect(result.warning).toContain('empty');
+  });
+
+  it('treats target:<empty> as a bare target (no type)', () => {
+    expect(parseConnectionList('foo:').list).toEqual([{ target: 'foo' }]);
+  });
+});
+
+describe('coerceAnnotationValues', () => {
+  it('routes known keys to blockMeta, unknown to metadata', () => {
+    const result = coerceAnnotationValues({
+      x: '400',
+      y: '200',
+      priority: 'high',
+      caption: 'hello',
+    });
+    expect(result.blockMeta).toEqual({ x: 400, y: 200 });
+    expect(result.metadata).toEqual({ priority: 'high', caption: 'hello' });
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('coerces startTime and duration to seconds', () => {
+    const result = coerceAnnotationValues({
+      startTime: '01:30',
+      duration: '00:15',
+    });
+    expect(result.blockMeta).toEqual({ startTime: 90, duration: 15 });
+  });
+
+  it('coerces connectsTo into a BlockConnection list', () => {
+    const result = coerceAnnotationValues({
+      connectsTo: 'foo:veryImportant,bar:requires,baz:requires',
+    });
+    expect(result.blockMeta.connectsTo).toEqual([
+      { target: 'foo', type: 'veryImportant' },
+      { target: 'bar', type: 'requires' },
+      { target: 'baz', type: 'requires' },
+    ]);
+  });
+
+  it('drops malformed numbers with a warning', () => {
+    const result = coerceAnnotationValues({ x: 'not-a-number' });
+    expect(result.blockMeta.x).toBeUndefined();
+    expect(result.metadata).toEqual({});
+    expect(result.warnings.length).toBe(1);
+    expect(result.warnings[0]).toContain('x');
+  });
+
+  it('drops malformed time values with a warning', () => {
+    const result = coerceAnnotationValues({ startTime: '99:bad' });
+    expect(result.blockMeta.startTime).toBeUndefined();
+    expect(result.warnings.length).toBe(1);
+  });
+
+  it('preserves empty connection list without warning', () => {
+    const result = coerceAnnotationValues({ connectsTo: '' });
+    expect(result.blockMeta.connectsTo).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('coerces transition metadata', () => {
+    const result = coerceAnnotationValues({
+      transition: 'random-bars',
+      transitionDuration: '850ms',
+      transitionDirection: 'left',
+    });
+
+    expect(result.blockMeta.transition).toEqual({
+      type: 'randomBars',
+      duration: 0.85,
+      direction: 'left',
+    });
+    expect(result.metadata).toEqual({});
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('drops malformed transition values with warnings', () => {
+    const result = coerceAnnotationValues({
+      transition: 'sideways-fold',
+      transitionDuration: 'fast',
+      transitionDirection: 'diagonal',
+    });
+
+    expect(result.blockMeta.transition).toBeUndefined();
+    expect(result.metadata).toEqual({});
+    expect(result.warnings).toHaveLength(3);
+  });
+
+  it('emits a warning for connectsTo with empty segments', () => {
+    const result = coerceAnnotationValues({ connectsTo: 'a,,b' });
+    expect(result.blockMeta.connectsTo).toEqual([{ target: 'a' }, { target: 'b' }]);
+    expect(result.warnings.length).toBe(1);
+  });
+
+  it('handles an empty input map', () => {
+    expect(coerceAnnotationValues({})).toEqual({
+      blockMeta: {},
+      metadata: {},
+      warnings: [],
+    });
+  });
+});
+
+describe('KNOWN_BLOCK_META_KEYS', () => {
+  it('lists the expected typed keys', () => {
+    expect(Object.keys(KNOWN_BLOCK_META_KEYS).sort()).toEqual([
+      'connectsTo',
+      'duration',
+      'startTime',
+      'transition',
+      'transitionDirection',
+      'transitionDuration',
+      'x',
+      'y',
+    ]);
+  });
+});
+
+describe('BLOCK_META_KEY_DESCRIPTORS', () => {
+  it('describes exactly the keys in KNOWN_BLOCK_META_KEYS', () => {
+    const described = BLOCK_META_KEY_DESCRIPTORS.map((d) => d.key).sort();
+    expect(described).toEqual(Object.keys(KNOWN_BLOCK_META_KEYS).sort());
+  });
+
+  it('has no duplicate keys', () => {
+    const keys = BLOCK_META_KEY_DESCRIPTORS.map((d) => d.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('gives each key either a closed value set or a format hint, never both', () => {
+    for (const d of BLOCK_META_KEY_DESCRIPTORS) {
+      expect(Boolean(d.values) !== Boolean(d.valueHint)).toBe(true);
+      expect(d.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('sources transition value sets from the canonical vocabulary', () => {
+    const transition = BLOCK_META_KEY_DESCRIPTORS.find((d) => d.key === 'transition');
+    const direction = BLOCK_META_KEY_DESCRIPTORS.find((d) => d.key === 'transitionDirection');
+    expect(transition?.values).toBe(TRANSITION_TYPES);
+    expect(direction?.values).toBe(TRANSITION_DIRECTIONS);
+  });
+});

package/src/__tests__/applyRenderStyle.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import { applyRenderStyleToLayers } from '../doc/utils/applyRenderStyle.js';
+import { resolveBlockTransition } from '../schemas/Transitions.js';
+import { DEFAULT_THEME, resolveTheme } from '../schemas/themeLibrary.js';
+import type { Theme } from '../schemas/Theme.js';
+import type { Layer } from '../schemas/Doc.js';
+
+function themeWith(patch: {
+  animationSpeed?: number;
+  ambientMotion?: boolean;
+  defaultImageAnimation?: Theme['renderStyle']['defaultImageAnimation'];
+  defaultTransition?: Theme['renderStyle']['defaultTransition'];
+}): Theme {
+  return {
+    ...DEFAULT_THEME,
+    style: {
+      ...DEFAULT_THEME.style,
+      ...(patch.animationSpeed != null ? { animationSpeed: patch.animationSpeed } : {}),
+    },
+    renderStyle: {
+      ...DEFAULT_THEME.renderStyle,
+      ...(patch.ambientMotion != null ? { ambientMotion: patch.ambientMotion } : {}),
+      ...(patch.defaultImageAnimation
+        ? { defaultImageAnimation: patch.defaultImageAnimation }
+        : {}),
+      ...(patch.defaultTransition ? { defaultTransition: patch.defaultTransition } : {}),
+    },
+  };
+}
+
+const fullBleedImage = (id = 'img'): Layer => ({
+  type: 'image',
+  id,
+  content: { src: 'x.jpg', alt: '' },
+  position: { x: 0, y: 0, width: '100%', height: '100%' },
+});
+
+const BLOCK = { id: 'b1', duration: 6 };
+
+describe('applyRenderStyleToLayers', () => {
+  it('is a no-op at animationSpeed 1.0 with no ambient motion (returns same objects)', () => {
+    const layers: Layer[] = [{ ...fullBleedImage(), animation: { type: 'fadeIn', duration: 2 } }];
+    const out = applyRenderStyleToLayers(layers, BLOCK, DEFAULT_THEME);
+    expect(out).toBe(layers);
+  });
+
+  it('scales duration and delay by animationSpeed', () => {
+    const layers: Layer[] = [
+      {
+        type: 'text',
+        id: 't',
+        content: { text: 'hi', style: { fontSize: 20, color: '#ffffff' } },
+        position: { x: '50%', y: '50%' },
+        animation: { type: 'fadeIn', duration: 2, delay: 1 },
+      },
+    ];
+    const out = applyRenderStyleToLayers(layers, BLOCK, themeWith({ animationSpeed: 0.5 }));
+    expect(out[0].animation).toEqual({ type: 'fadeIn', duration: 1, delay: 0.5 });
+    // Input untouched (pure)
+    expect(layers[0].animation).toEqual({ type: 'fadeIn', duration: 2, delay: 1 });
+  });
+
+  it('gives full-bleed cover imagery a deterministic ambient Ken Burns', () => {
+    const theme = themeWith({ ambientMotion: true });
+    const a = applyRenderStyleToLayers([fullBleedImage()], BLOCK, theme);
+    const b = applyRenderStyleToLayers([fullBleedImage()], BLOCK, theme);
+    expect(a[0].animation?.type).toBe('slowZoom');
+    expect(a[0].animation?.duration).toBeGreaterThanOrEqual(8);
+    // Deterministic: same block+layer id → same variant
+    expect(a[0].animation).toEqual(b[0].animation);
+    // Different layer id → independent (usually different) but still defined
+    const c = applyRenderStyleToLayers([fullBleedImage('other')], BLOCK, theme);
+    expect(c[0].animation?.type).toBe('slowZoom');
+  });
+
+  it("treats defaultImageAnimation 'slowZoom' as ambient motion", () => {
+    const out = applyRenderStyleToLayers(
+      [fullBleedImage()],
+      BLOCK,
+      themeWith({ defaultImageAnimation: 'slowZoom' }),
+    );
+    expect(out[0].animation?.type).toBe('slowZoom');
+  });
+
+  it('never overrides an authored animation, including type none', () => {
+    const theme = themeWith({ ambientMotion: true });
+    const none: Layer = { ...fullBleedImage(), animation: { type: 'none' } };
+    const authored: Layer = {
+      ...fullBleedImage('a2'),
+      animation: { type: 'fadeIn', duration: 3 },
+    };
+    const out = applyRenderStyleToLayers([none, authored], BLOCK, theme);
+    expect(out[0].animation).toEqual({ type: 'none' });
+    expect(out[1].animation?.type).toBe('fadeIn');
+  });
+
+  it('does not blanket-animate partial or contain-fit imagery', () => {
+    const theme = themeWith({ ambientMotion: true });
+    const strip: Layer = {
+      type: 'image',
+      id: 'strip',
+      content: { src: 'x.jpg', alt: '' },
+      position: { x: '65%', y: 0, width: '35%', height: '100%' },
+    };
+    const contained: Layer = {
+      type: 'image',
+      id: 'contained',
+      content: { src: 'x.jpg', alt: '', fit: 'contain' },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+    const out = applyRenderStyleToLayers([strip, contained], BLOCK, theme);
+    expect(out[0].animation).toBeUndefined();
+    expect(out[1].animation).toBeUndefined();
+  });
+});
+
+describe('resolveBlockTransition', () => {
+  const theme = themeWith({ defaultTransition: { type: 'dissolve', duration: 1.2 } });
+
+  it('authored transition always wins', () => {
+    const t = resolveBlockTransition({ transition: { type: 'cut' } }, theme, 3);
+    expect(t).toEqual({ type: 'cut' });
+  });
+
+  it('falls back to the theme default for blocks after the first', () => {
+    expect(resolveBlockTransition({}, theme, 1)).toEqual({ type: 'dissolve', duration: 1.2 });
+  });
+
+  it('never applies a theme default to block 0', () => {
+    expect(resolveBlockTransition({}, theme, 0)).toBeUndefined();
+  });
+
+  it('returns undefined when neither block nor theme specify one', () => {
+    const bare: Theme = {
+      ...DEFAULT_THEME,
+      renderStyle: { ...DEFAULT_THEME.renderStyle, defaultTransition: undefined },
+    };
+    expect(resolveBlockTransition({}, bare, 2)).toBeUndefined();
+  });
+
+  it('documentary (built-in) authors a default transition that now resolves', () => {
+    const documentary = resolveTheme('documentary');
+    const t = resolveBlockTransition({}, documentary, 1);
+    expect(t?.type).toBe('fade');
+  });
+});

package/src/__tests__/atmosphereLayers.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { expandPersistentLayer } from '../doc/templates/persistentLayers.js';
+import { cssFilterForTreatment } from '../doc/utils/imageTreatment.js';
+import { themedImageTreatment } from '../doc/utils/themeUtils.js';
+import { createTemplateContext } from '../schemas/BlockTemplates.js';
+import { DEFAULT_THEME, resolveTheme } from '../schemas/themeLibrary.js';
+import { validateTheme } from '../schemas/themeValidator.js';
+import { THEMES } from '../schemas/themeLibrary.js';
+import type { ShapeLayer, ImageLayer } from '../schemas/Doc.js';
+
+describe('atmosphere persistent layers', () => {
+  it('patternBackground expands dots/grid/diagonal to an SVG pattern fill', () => {
+    const [layer] = expandPersistentLayer({
+      template: 'patternBackground',
+      config: { type: 'patternBackground', pattern: 'grid', color: '#00e5ff', opacity: 0.04 },
+    }) as ShapeLayer[];
+    expect(layer.type).toBe('shape');
+    expect(layer.content.pattern).toEqual({
+      kind: 'grid',
+      color: '#00e5ff',
+      size: 24,
+      opacity: 0.04,
+    });
+  });
+
+  it('patternBackground noise expands to a grain filter rect', () => {
+    const [layer] = expandPersistentLayer({
+      template: 'patternBackground',
+      config: { type: 'patternBackground', pattern: 'noise', opacity: 0.05 },
+    }) as ShapeLayer[];
+    expect(layer.content.filter).toEqual({ type: 'noise', opacity: 0.05 });
+  });
+
+  it('vignette expands to a radial gradient rect with strength-scaled edge', () => {
+    const [layer] = expandPersistentLayer({
+      template: 'vignette',
+      config: { type: 'vignette', strength: 0.4 },
+    }) as ShapeLayer[];
+    expect(layer.content.fill).toContain('radial-gradient');
+    expect(layer.content.fill).toContain('rgba(0, 0, 0, 0.4)');
+  });
+
+  it('ambientGradient derives colors from the theme and drifts slowly', () => {
+    const theme = resolveTheme('gezellig');
+    const [layer] = expandPersistentLayer(
+      { template: 'ambientGradient', config: { type: 'ambientGradient' } },
+      theme,
+    ) as ShapeLayer[];
+    expect(layer.content.fill).toContain(theme.colors.backgroundLight);
+    expect(layer.animation?.type).toBe('slowZoom');
+    expect(layer.animation?.duration).toBe(40);
+    // Oversized so the pan never reveals the frame edge
+    expect(layer.position.width).toBe('110%');
+  });
+
+  it('imageBackground passes blur through to the image layer', () => {
+    const [image] = expandPersistentLayer({
+      template: 'imageBackground',
+      config: { type: 'imageBackground', src: 'bg.jpg', blur: 12 },
+    }) as ImageLayer[];
+    expect(image.content.blur).toBe(12);
+  });
+
+  it('every built-in theme still validates with its atmosphere layers', () => {
+    for (const [id, theme] of Object.entries(THEMES)) {
+      const result = validateTheme(theme);
+      expect(result.valid, `theme ${id}: ${JSON.stringify(result.errors)}`).toBe(true);
+    }
+  });
+});
+
+describe('image treatments', () => {
+  it('mono produces a grayscale filter scaled by strength', () => {
+    expect(cssFilterForTreatment({ type: 'mono', strength: 1 })).toContain('grayscale(1)');
+    expect(cssFilterForTreatment({ type: 'mono', strength: 0.5 })).toContain('grayscale(0.5)');
+  });
+
+  it('duotone rotates hue toward the tint color', () => {
+    // #ff0000 has hue 0 → rotation 0 - 40 = -40deg
+    const f = cssFilterForTreatment({ type: 'duotone', color: '#ff0000' });
+    expect(f).toContain('grayscale(1)');
+    expect(f).toContain('hue-rotate(-40deg)');
+  });
+
+  it('none / absent treatments produce no filter', () => {
+    expect(cssFilterForTreatment({ type: 'none' })).toBeUndefined();
+    expect(cssFilterForTreatment(undefined)).toBeUndefined();
+  });
+
+  it('blur composes with (or without) a treatment', () => {
+    expect(cssFilterForTreatment(undefined, 12)).toBe('blur(12px)');
+    expect(cssFilterForTreatment({ type: 'mono' }, 8)).toMatch(/^blur\(8px\) grayscale/);
+  });
+
+  it('themedImageTreatment: block override wins, none opts out, duotone tints from primary', () => {
+    const documentary = resolveTheme('documentary');
+    const ctx = createTemplateContext(documentary, 0, 1);
+    // Theme authors mono
+    expect(themedImageTreatment(ctx)?.type).toBe('mono');
+    // Block opts out
+    expect(themedImageTreatment(ctx, 'none')).toBeUndefined();
+    // Block forces duotone → tint defaults to theme primary
+    expect(themedImageTreatment(ctx, 'duotone')?.color).toBe(documentary.colors.primary);
+    // Standard theme has no treatment
+    const plainCtx = createTemplateContext(DEFAULT_THEME, 0, 1);
+    expect(themedImageTreatment(plainCtx)).toBeUndefined();
+  });
+});

package/src/__tests__/attrTokens.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import {
+  tokenizeAttrTokens,
+  splitKeyValueToken,
+  unquoteAttrValue,
+  needsQuoting,
+  quoteAttrValue,
+  matchTrailingTemplateAnnotation,
+  matchTrailingPandocAttr,
+} from '../markdown/attrTokens.js';
+
+describe('tokenizeAttrTokens', () => {
+  it('splits bare tokens on whitespace', () => {
+    expect(tokenizeAttrTokens('chart colorScheme=blue size=large')).toEqual([
+      'chart',
+      'colorScheme=blue',
+      'size=large',
+    ]);
+  });
+
+  it('keeps a double-quoted value as one token', () => {
+    expect(tokenizeAttrTokens('caption="Beach at sunset" columns=3')).toEqual([
+      'caption="Beach at sunset"',
+      'columns=3',
+    ]);
+  });
+
+  it('keeps a single-quoted value as one token', () => {
+    expect(tokenizeAttrTokens("caption='Beach at sunset'")).toEqual(["caption='Beach at sunset'"]);
+  });
+
+  it('treats a quote mid-value as a literal character', () => {
+    // The quote in O'Brien is not at a value start, so it must not open a
+    // quoted run and swallow the following token.
+    expect(tokenizeAttrTokens("attribution=O'Brien x=4")).toEqual(["attribution=O'Brien", 'x=4']);
+  });
+
+  it('preserves escape pairs inside a quoted run', () => {
+    expect(tokenizeAttrTokens('label="he said \\"hi\\""')).toEqual(['label="he said \\"hi\\""']);
+  });
+
+  it('tolerates an unbalanced opening quote (run extends to end of input)', () => {
+    expect(tokenizeAttrTokens('caption="oops trailing')).toEqual(['caption="oops trailing']);
+  });
+
+  it('keeps a bare quoted token verbatim', () => {
+    expect(tokenizeAttrTokens('"just a string"')).toEqual(['"just a string"']);
+  });
+});
+
+describe('splitKeyValueToken / unquoteAttrValue', () => {
+  it('splits on the first =', () => {
+    expect(splitKeyValueToken('a=b=c')).toEqual({ key: 'a', value: 'b=c' });
+  });
+
+  it('returns null for tokens without = past the first character', () => {
+    expect(splitKeyValueToken('chart')).toBeNull();
+    expect(splitKeyValueToken('#id')).toBeNull();
+    expect(splitKeyValueToken('=leading')).toBeNull();
+  });
+
+  it('strips matching double quotes and unescapes', () => {
+    expect(splitKeyValueToken('label="he said \\"hi\\""')).toEqual({
+      key: 'label',
+      value: 'he said "hi"',
+    });
+  });
+
+  it('strips matching single quotes and unescapes', () => {
+    expect(splitKeyValueToken("label='it\\'s here'")).toEqual({ key: 'label', value: "it's here" });
+  });
+
+  it('leaves unmatched quotes verbatim', () => {
+    expect(unquoteAttrValue('"unbalanced')).toBe('"unbalanced');
+    expect(unquoteAttrValue('"')).toBe('"');
+  });
+
+  it('leaves backslashes before other characters alone', () => {
+    expect(unquoteAttrValue('"C:\\temp"')).toBe('C:\\temp');
+  });
+});
+
+describe('needsQuoting / quoteAttrValue', () => {
+  it('passes simple values through bare', () => {
+    expect(quoteAttrValue('blue')).toBe('blue');
+    expect(quoteAttrValue('a,b,c')).toBe('a,b,c');
+    expect(quoteAttrValue('foo:flow')).toBe('foo:flow');
+  });
+
+  it('double-quotes values with spaces', () => {
+    expect(quoteAttrValue('Beach at sunset')).toBe('"Beach at sunset"');
+  });
+
+  it('quotes empty values', () => {
+    expect(quoteAttrValue('')).toBe('""');
+  });
+
+  it('quotes values containing brackets or braces', () => {
+    expect(needsQuoting('a]b')).toBe(true);
+    expect(quoteAttrValue('a]b')).toBe('"a]b"');
+    expect(quoteAttrValue('a}b')).toBe('"a}b"');
+  });
+
+  it('switches to single quotes when the value contains a double quote', () => {
+    expect(quoteAttrValue('She said "hi"')).toBe('\'She said "hi"\'');
+  });
+
+  it('falls back to double quotes with escapes when both quote chars appear', () => {
+    expect(quoteAttrValue('it\'s a "thing"')).toBe('"it\'s a \\"thing\\""');
+  });
+
+  it('round-trips through tokenize + split', () => {
+    const values = ['Beach at sunset', 'a ] b', 'She said "hi"', "it's fine", 'C:\\temp', ''];
+    for (const value of values) {
+      const tokens = tokenizeAttrTokens(`key=${quoteAttrValue(value)}`);
+      expect(tokens).toHaveLength(1);
+      expect(splitKeyValueToken(tokens[0])).toEqual({ key: 'key', value });
+    }
+  });
+});
+
+describe('matchTrailingTemplateAnnotation', () => {
+  it('matches a simple trailing annotation', () => {
+    const m = matchTrailingTemplateAnnotation('Getting Started {[comparisonBar]}');
+    expect(m?.inner).toBe('comparisonBar');
+  });
+
+  it('allows ] inside a quoted value', () => {
+    const m = matchTrailingTemplateAnnotation('X {[quote text="a ] b"]}');
+    expect(m?.inner).toBe('quote text="a ] b"');
+  });
+
+  it('falls back to the legacy grammar for unbalanced quotes', () => {
+    const m = matchTrailingTemplateAnnotation('X {[quote text="oops]}');
+    expect(m?.inner).toBe('quote text="oops');
+  });
+
+  it('still tolerates an accidentally doubled trailing ]}', () => {
+    const m = matchTrailingTemplateAnnotation('X {[comparisonBar]}]}');
+    expect(m?.inner).toBe('comparisonBar');
+  });
+
+  it('rejects non-trailing annotations', () => {
+    expect(matchTrailingTemplateAnnotation('The {[chart]} section')).toBeNull();
+  });
+});
+
+describe('matchTrailingPandocAttr', () => {
+  it('matches a simple trailing block', () => {
+    const m = matchTrailingPandocAttr('Section {#intro .wide x=4}');
+    expect(m?.inner).toBe('#intro .wide x=4');
+  });
+
+  it('allows } inside a quoted value', () => {
+    const m = matchTrailingPandocAttr('X {caption="a } b"}');
+    expect(m?.inner).toBe('caption="a } b"');
+  });
+
+  it('does not match the {[…]} template form', () => {
+    expect(matchTrailingPandocAttr('X {[chart]}')).toBeNull();
+  });
+});