@bendyline/squisq 1.4.1 → 1.5.0

package/dist/{types-BdZkdJ3z.d.ts → types-DlAZ7MW4.d.ts}

@@ -1,3 +1,53 @@
+/**
+ * Shared transition vocabulary for block-to-block slide changes.
+ *
+ * The canonical names are based on PowerPoint / PresentationML transition
+ * names where possible, with a few legacy renderer aliases kept so older
+ * Squisq documents continue to work.
+ */
+declare const DEFAULT_TRANSITION_DURATION_SECONDS = 0.7;
+declare const TRANSITION_TYPES: readonly ["cut", "fade", "dissolve", "push", "wipe", "split", "reveal", "randomBars", "shape", "uncover", "cover", "zoom", "pan", "flash", "fallOver", "drape", "curtains", "wind", "prestige", "fracture", "crush", "peelOff", "pageCurl", "airplane", "origami", "checkerboard", "blinds", "clock", "ripple", "honeycomb", "glitter", "vortex", "shred", "switch", "flip", "gallery", "cube", "doors", "box", "ferrisWheel", "conveyor", "rotate", "window", "orbit", "flyThrough", "morph", "checker", "circle", "comb", "diamond", "newsflash", "plus", "pull", "random", "randomBar", "strips", "wedge", "wheel", "prism", "warp", "ferris", "flythrough", "wheelReverse", "pageCurlDouble", "pageCurlSingle", "slideLeft", "slideRight", "slideUp", "slideDown"];
+type TransitionType = (typeof TRANSITION_TYPES)[number];
+declare const TRANSITION_DIRECTIONS: readonly ["left", "right", "up", "down", "in", "out", "horizontal", "vertical"];
+type TransitionDirection = (typeof TRANSITION_DIRECTIONS)[number];
+/**
+ * Transition between blocks.
+ *
+ * A block's transition is the lead-in from the previous block. The same
+ * transition drives the entering block and the previous block's exit.
+ */
+interface Transition {
+    /** Transition type */
+    type: TransitionType;
+    /** Duration in seconds. Defaults to DEFAULT_TRANSITION_DURATION_SECONDS. */
+    duration?: number;
+    /** Optional direction/variant for directional transitions. */
+    direction?: TransitionDirection;
+}
+declare function isTransitionType(value: string): value is TransitionType;
+declare function normalizeTransitionType(value: string): TransitionType | null;
+declare function normalizeTransitionDirection(value: string): TransitionDirection | null;
+declare function resolveTransitionDuration(transition: Transition | undefined, fallback?: number): number;
+/**
+ * Resolve the effective transition for a block: the authored value wins
+ * (markdown frontmatter and transform styles both write `block.transition`
+ * upstream), then the theme's `renderStyle.defaultTransition`, then
+ * `undefined` (the player's built-in default).
+ *
+ * Block 0 never gets a theme default — an entrance transition on the first
+ * block would dim the opening frames of every exported video.
+ *
+ * The theme parameter is structural (not `Theme`) to avoid a schema import
+ * cycle; pass any resolved theme.
+ */
+declare function resolveBlockTransition(block: {
+    transition?: Transition;
+}, theme: {
+    renderStyle: {
+        defaultTransition?: Transition;
+    };
+}, blockIndex: number): Transition | undefined;
+
 /**
  * Markdown DOM Types
  *
@@ -100,6 +150,63 @@ interface HeadingTemplateAnnotation {
     /** Optional key-value parameters (remaining `key=value` tokens) */
     params?: Record<string, string>;
 }
+/**
+ * A directed connection from one block to another, parsed from a heading
+ * attribute `connectsTo=target1,target2:type,target3`. Mirrors the schema
+ * `BlockConnection` type — duplicated here so this module stays
+ * dependency-free from the doc schema.
+ */
+interface BlockConnection {
+    /** Target block id. */
+    target: string;
+    /** Optional connection type/label (e.g., "flow", "requires"). */
+    type?: string;
+}
+/**
+ * Pandoc-style heading attribute block, parsed from `{#id .class key=value}`
+ * appearing at the end of a heading line (alongside, or instead of, the
+ * squisq-native `{[templateName …]}` block).
+ *
+ * @example
+ * ```markdown
+ * ## Architecture {#arch x=600 y=300 connectsTo=foo:flow,bar:requires}
+ * ```
+ * →
+ * ```ts
+ * {
+ *   id: 'arch',
+ *   params: { x: '600', y: '300', connectsTo: 'foo:flow,bar:requires' },
+ *   blockMeta: {
+ *     x: 600,
+ *     y: 300,
+ *     connectsTo: [{ target: 'foo', type: 'flow' }, { target: 'bar', type: 'requires' }],
+ *   },
+ * }
+ * ```
+ *
+ * `params` carries the raw pre-coercion strings (lossless for round-tripping),
+ * while `blockMeta` carries the typed values for known keys. Unknown keys flow
+ * to `metadata`.
+ */
+interface HeadingAttributes {
+    /** Block id from `#identifier` (overrides slug-from-heading). */
+    id?: string;
+    /** Class tokens from `.classname` (reserved for downstream use). */
+    classes?: string[];
+    /** All key=value attributes as raw strings (lossless source for serialization). */
+    params?: Record<string, string>;
+    /** Typed values for known block-meta keys (coerced from `params`). */
+    blockMeta?: {
+        x?: number;
+        y?: number;
+        startTime?: number;
+        duration?: number;
+        connectsTo?: BlockConnection[];
+        transition?: Transition;
+    };
+    /** Subset of `params` whose keys are NOT in the known-key registry. */
+    metadata?: Record<string, string>;
+}
 /**
  * ATX or setext heading (# Heading).
  */
@@ -116,6 +223,13 @@ interface MarkdownHeading extends MarkdownNodeBase {
      * stringification, so it round-trips transparently.
      */
     templateAnnotation?: HeadingTemplateAnnotation;
+    /**
+     * Pandoc-style heading attributes parsed from trailing `{#id .class key=value}`
+     * syntax. Independent from `templateAnnotation` — both may appear on the
+     * same heading in either order. Stripped from `children` during parsing
+     * and re-injected during stringification.
+     */
+    attributes?: HeadingAttributes;
 }
 /**
  * A paragraph of inline content.
@@ -528,4 +642,4 @@ interface StringifyOptions {
     setext?: boolean;
 }
 
-export type { MarkdownLinkReference as A, MarkdownList as B, MarkdownListItem as C, MarkdownMathBlock as D, MarkdownMention as E, MarkdownNode as F, MarkdownParagraph as G, HeadingTemplateAnnotation as H, MarkdownPoint as I, MarkdownSourcePosition as J, MarkdownStrikethrough as K, MarkdownStrong as L, MarkdownBlockNode as M, MarkdownTable as N, MarkdownTableCell as O, MarkdownTableRow as P, MarkdownText as Q, MarkdownTextDirective as R, MarkdownThematicBreak as S, ParseOptions as T, StringifyOptions as U, HtmlComment as a, HtmlElement as b, HtmlNode as c, HtmlText as d, MarkdownBlockquote as e, MarkdownBreak as f, MarkdownCodeBlock as g, MarkdownContainerDirective as h, MarkdownDefinitionDescription as i, MarkdownDefinitionList as j, MarkdownDefinitionTerm as k, MarkdownDocument as l, MarkdownEmphasis as m, MarkdownFootnoteDefinition as n, MarkdownFootnoteReference as o, MarkdownHeading as p, MarkdownHtmlBlock as q, MarkdownImage as r, MarkdownImageReference as s, MarkdownInlineCode as t, MarkdownInlineHtml as u, MarkdownInlineMath as v, MarkdownInlineNode as w, MarkdownLeafDirective as x, MarkdownLink as y, MarkdownLinkDefinition as z };
+export { type TransitionType as $, type MarkdownLinkDefinition as A, type MarkdownLinkReference as B, type MarkdownList as C, DEFAULT_TRANSITION_DURATION_SECONDS as D, type MarkdownListItem as E, type MarkdownMathBlock as F, type MarkdownMention as G, type HeadingAttributes as H, type MarkdownNode as I, type MarkdownParagraph as J, type MarkdownPoint as K, type MarkdownSourcePosition as L, type MarkdownBlockNode as M, type MarkdownStrikethrough as N, type MarkdownStrong as O, type MarkdownTable as P, type MarkdownTableCell as Q, type MarkdownTableRow as R, type MarkdownText as S, type MarkdownTextDirective as T, type MarkdownThematicBreak as U, type ParseOptions as V, type StringifyOptions as W, TRANSITION_DIRECTIONS as X, TRANSITION_TYPES as Y, type Transition as Z, type TransitionDirection as _, type HeadingTemplateAnnotation as a, isTransitionType as a0, normalizeTransitionDirection as a1, normalizeTransitionType as a2, resolveBlockTransition as a3, resolveTransitionDuration as a4, type HtmlComment as b, type HtmlElement as c, type HtmlNode as d, type HtmlText as e, type MarkdownBlockquote as f, type MarkdownBreak as g, type MarkdownCodeBlock as h, type MarkdownContainerDirective as i, type MarkdownDefinitionDescription as j, type MarkdownDefinitionList as k, type MarkdownDefinitionTerm as l, type MarkdownDocument as m, type MarkdownEmphasis as n, type MarkdownFootnoteDefinition as o, type MarkdownFootnoteReference as p, type MarkdownHeading as q, type MarkdownHtmlBlock as r, type MarkdownImage as s, type MarkdownImageReference as t, type MarkdownInlineCode as u, type MarkdownInlineHtml as v, type MarkdownInlineMath as w, type MarkdownInlineNode as x, type MarkdownLeafDirective as y, type MarkdownLink as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",
@@ -106,6 +106,11 @@
       "import": "./dist/icons/index.js",
       "default": "./dist/icons/index.js"
     },
+    "./icon-marker": {
+      "types": "./dist/icons/inlineIconMarker.d.ts",
+      "import": "./dist/icons/inlineIconMarker.js",
+      "default": "./dist/icons/inlineIconMarker.js"
+    },
     "./recommend": {
       "types": "./dist/recommend/index.d.ts",
       "import": "./dist/recommend/index.js",

package/src/__tests__/animationUtils.test.ts

@@ -5,6 +5,7 @@ import {
   getTransitionClass,
   getAnimationProgress,
 } from '../doc/utils/animationUtils';
+import { TRANSITION_TYPES } from '../schemas/Transitions';
 
 describe('getAnimationStyle', () => {
   it('returns empty for undefined animation', () => {
@@ -57,6 +58,45 @@ describe('getTransitionClass', () => {
   it('returns exit class', () => {
     expect(getTransitionClass('dissolve', false)).toBe('transition-dissolve-exit');
   });
+
+  it('returns no class for cut', () => {
+    expect(getTransitionClass('cut', true)).toBe('');
+  });
+
+  it('maps PowerPoint-style transitions to supported visual classes', () => {
+    for (const type of TRANSITION_TYPES) {
+      if (type === 'cut') continue;
+      expect(getTransitionClass(type, true), type).toMatch(/^transition-.+-enter$/);
+      expect(getTransitionClass(type, false), type).toMatch(/^transition-.+-exit$/);
+    }
+  });
+
+  it('keeps the PowerPoint transition vocabulary visually expressive', () => {
+    const families = new Set(
+      TRANSITION_TYPES.flatMap((type) => {
+        const className = getTransitionClass(type, true);
+        const match = /^transition-(.+)-enter$/.exec(className);
+        return match ? [match[1]] : [];
+      }),
+    );
+
+    expect(families.size).toBeGreaterThanOrEqual(50);
+  });
+
+  it('maps aliases to stable visual families', () => {
+    expect(getTransitionClass('randomBars', true)).toBe('transition-randomBarsVertical-enter');
+    expect(getTransitionClass('flyThrough', true)).toBe('transition-flyThrough-enter');
+    expect(getTransitionClass('flythrough', true)).toBe('transition-flyThrough-enter');
+    expect(getTransitionClass('cube', true)).toBe('transition-cube-enter');
+    expect(getTransitionClass('ferris', true)).toBe('transition-ferrisWheel-enter');
+  });
+
+  it('honors transition directions for directional families', () => {
+    expect(getTransitionClass('wipe', true, 'right')).toBe('transition-wipeRight-enter');
+    expect(getTransitionClass('push', false, 'up')).toBe('transition-pushUp-exit');
+    expect(getTransitionClass('split', true, 'vertical')).toBe('transition-splitVertical-enter');
+    expect(getTransitionClass('blinds', false, 'vertical')).toBe('transition-blindsVertical-exit');
+  });
 });
 
 describe('getAnimationProgress', () => {

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