@bendyline/squisq 2.0.0 → 2.1.0

package/src/__tests__/pageStyle.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect } from 'vitest';
+import { validateTheme } from '../schemas/themeValidator.js';
+import { compileTheme } from '../schemas/themeCompile.js';
+import { defaultPageStyle } from '../schemas/pageStyleDefaults.js';
+import { THEMES, DEFAULT_THEME } from '../schemas/themeLibrary.js';
+import { PAGE_SECTION_KINDS } from '../schemas/PageStyle.js';
+import type { Theme } from '../schemas/Theme.js';
+import type { ThemePageStyle } from '../schemas/PageStyle.js';
+import {
+  readCustomThemesFromFrontmatter,
+  writeCustomThemesToFrontmatter,
+} from '../doc/customThemesFrontmatter.js';
+
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v)) as T;
+}
+
+function themed(pageStyle: unknown): Record<string, unknown> {
+  return { ...clone(DEFAULT_THEME as unknown as Record<string, unknown>), pageStyle };
+}
+
+const VALID_PAGE_STYLE: ThemePageStyle = {
+  family: 'clean',
+  tokens: {
+    contentMaxWidth: 760,
+    wideMaxWidth: 1100,
+    sectionSpacing: 'comfortable',
+    cornerRadius: 8,
+    divider: 'hairline',
+    backgroundRhythm: 'alternate',
+    heroStyle: 'stacked',
+    headingTreatment: { eyebrow: 'kicker', scale: 'regular' },
+    imageFraming: 'rounded',
+    shadow: 'soft',
+    quoteMark: 'accent-bar',
+    numeralStyle: 'plain',
+  },
+  accentRotation: { strategy: 'cycle' },
+};
+
+describe('pageStyle validation', () => {
+  it('accepts a theme without pageStyle (optional)', () => {
+    const theme = clone(DEFAULT_THEME) as unknown as Record<string, unknown>;
+    delete theme.pageStyle;
+    expect(validateTheme(theme).valid).toBe(true);
+  });
+
+  it('accepts a complete valid pageStyle', () => {
+    expect(validateTheme(themed(clone(VALID_PAGE_STYLE))).valid).toBe(true);
+  });
+
+  it('rejects an unknown family', () => {
+    const ps = clone(VALID_PAGE_STYLE) as unknown as Record<string, unknown>;
+    ps.family = 'baroque';
+    const result = validateTheme(themed(ps));
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('pageStyle.family');
+  });
+
+  it('rejects a bad token enum value', () => {
+    const ps = clone(VALID_PAGE_STYLE);
+    (ps.tokens as unknown as Record<string, unknown>).divider = 'lasers';
+    const result = validateTheme(themed(ps));
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('pageStyle.tokens.divider');
+  });
+
+  it('rejects non-numeric column widths', () => {
+    const ps = clone(VALID_PAGE_STYLE);
+    (ps.tokens as unknown as Record<string, unknown>).contentMaxWidth = '760px';
+    const result = validateTheme(themed(ps));
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('pageStyle.tokens.contentMaxWidth');
+  });
+
+  it('rejects unknown section-kind keys in sections', () => {
+    const ps = clone(VALID_PAGE_STYLE);
+    ps.sections = { jumbotron: { variant: 'x' } } as unknown as ThemePageStyle['sections'];
+    const result = validateTheme(themed(ps));
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('pageStyle.sections.jumbotron');
+  });
+
+  it('rejects non-scalar hint values', () => {
+    const ps = clone(VALID_PAGE_STYLE);
+    ps.templates = {
+      diagram: { hints: { frame: { nested: true } } },
+    } as unknown as ThemePageStyle['templates'];
+    const result = validateTheme(themed(ps));
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('pageStyle.templates.diagram.hints.frame');
+  });
+
+  it('requires accentRotation with a known strategy', () => {
+    const ps = clone(VALID_PAGE_STYLE) as unknown as Record<string, unknown>;
+    delete ps.accentRotation;
+    const missing = validateTheme(themed(ps));
+    expect(missing.valid).toBe(false);
+    expect(missing.errors.map((e) => e.path)).toContain('pageStyle.accentRotation');
+
+    const ps2 = clone(VALID_PAGE_STYLE);
+    ps2.accentRotation = { strategy: 'random' } as unknown as ThemePageStyle['accentRotation'];
+    const bad = validateTheme(themed(ps2));
+    expect(bad.valid).toBe(false);
+    expect(bad.errors.map((e) => e.path)).toContain('pageStyle.accentRotation.strategy');
+  });
+
+  it('rejects a section override that remaps to an invalid kind', () => {
+    const ps = clone(VALID_PAGE_STYLE);
+    ps.sections = {
+      'quote-band': { kind: 'jumbo' },
+    } as unknown as ThemePageStyle['sections'];
+    const result = validateTheme(themed(ps));
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.path)).toContain('pageStyle.sections.quote-band.kind');
+  });
+});
+
+describe('built-in theme pageStyle art direction', () => {
+  it('every built-in theme declares an explicit pageStyle', () => {
+    for (const [id, theme] of Object.entries(THEMES)) {
+      expect(theme.pageStyle, `theme "${id}" is missing pageStyle`).toBeDefined();
+    }
+  });
+
+  it('every built-in art direction is pairwise distinct', () => {
+    // Two themes may share a family, but their page identity — the tuple of
+    // (family, heroStyle, divider, backgroundRhythm, imageFraming) — must
+    // differ so each theme reads as its own website design.
+    const seen = new Map<string, string>();
+    for (const [id, theme] of Object.entries(THEMES)) {
+      const ps = theme.pageStyle!;
+      const tuple = [
+        ps.family,
+        ps.tokens.heroStyle,
+        ps.tokens.divider,
+        ps.tokens.backgroundRhythm,
+        ps.tokens.imageFraming,
+      ].join('|');
+      const prior = seen.get(tuple);
+      expect(prior, `themes "${prior}" and "${id}" share art direction tuple ${tuple}`).toBe(
+        undefined,
+      );
+      seen.set(tuple, id);
+    }
+  });
+
+  it('section override keys reference valid kinds in every built-in', () => {
+    for (const theme of Object.values(THEMES)) {
+      for (const key of Object.keys(theme.pageStyle?.sections ?? {})) {
+        expect(PAGE_SECTION_KINDS).toContain(key);
+      }
+    }
+  });
+});
+
+describe('defaultPageStyle derivation', () => {
+  it('maps renderStyle.name to the matching design family', () => {
+    const base = clone(DEFAULT_THEME);
+    const cases: Array<[string, string]> = [
+      ['documentary', 'documentary'],
+      ['magazine', 'editorial'],
+      ['bold', 'brutalist'],
+      ['tech-dark', 'terminal'],
+      ['cinematic', 'cinematic'],
+      ['warm-earth', 'organic'],
+      ['gezellig', 'soft'],
+      ['standard', 'clean'],
+      ['some-unknown-style', 'clean'],
+    ];
+    for (const [renderName, family] of cases) {
+      const theme = { ...base, renderStyle: { ...base.renderStyle, name: renderName } } as Theme;
+      expect(defaultPageStyle(theme).family, renderName).toBe(family);
+    }
+  });
+
+  it('derives cornerRadius and framing from style fields', () => {
+    const base = clone(DEFAULT_THEME);
+    const rounded = defaultPageStyle({ ...base, style: { ...base.style, borderRadius: 12 } });
+    expect(rounded.tokens.cornerRadius).toBe(12);
+    expect(rounded.tokens.imageFraming).toBe('rounded');
+
+    const flush = defaultPageStyle({ ...base, style: { ...base.style, borderRadius: 0 } });
+    expect(flush.tokens.imageFraming).toBe('flush');
+
+    const mono = defaultPageStyle({
+      ...base,
+      style: { ...base.style, imageTreatment: { type: 'mono', strength: 0.4 } },
+    });
+    expect(mono.tokens.imageFraming).toBe('letterboxed');
+  });
+
+  it('derives pattern from persistentLayers and shadow from textShadow', () => {
+    const base = clone(DEFAULT_THEME);
+    const patterned = defaultPageStyle({
+      ...base,
+      persistentLayers: {
+        topLayers: [
+          {
+            template: 'patternBackground',
+            config: { type: 'patternBackground', pattern: 'grid' },
+          },
+        ],
+      },
+    } as Theme);
+    expect(patterned.tokens.pattern).toBe('grid');
+
+    const shadowed = defaultPageStyle({ ...base, style: { ...base.style, textShadow: true } });
+    expect(shadowed.tokens.shadow).toBe('soft');
+    const flat = defaultPageStyle({ ...base, style: { ...base.style, textShadow: false } });
+    expect(flat.tokens.shadow).toBe('none');
+  });
+
+  it('derived styles validate', () => {
+    for (const theme of Object.values(THEMES)) {
+      const stripped = clone(theme) as unknown as Record<string, unknown>;
+      delete stripped.pageStyle;
+      const derived = { ...stripped, pageStyle: defaultPageStyle(stripped as unknown as Theme) };
+      expect(validateTheme(derived).valid).toBe(true);
+    }
+  });
+});
+
+describe('compileTheme pageStyle behavior', () => {
+  it('fills pageStyle when the partial omits it', () => {
+    const compiled = compileTheme({ id: 'test-fill', name: 'Test Fill' });
+    expect(compiled.pageStyle).toBeDefined();
+    expect(compiled.pageStyle!.family).toBe('clean');
+  });
+
+  it('preserves an explicit pageStyle untouched', () => {
+    const explicit = clone(VALID_PAGE_STYLE);
+    explicit.family = 'brutalist';
+    const compiled = compileTheme({
+      id: 'test-explicit',
+      name: 'Test Explicit',
+      pageStyle: explicit,
+    });
+    expect(compiled.pageStyle!.family).toBe('brutalist');
+  });
+
+  it('inherits the base theme pageStyle through compile', () => {
+    const compiled = compileTheme({ id: 'derived', name: 'Derived' }, { base: THEMES.magazine });
+    expect(compiled.pageStyle).toEqual(THEMES.magazine.pageStyle);
+  });
+});
+
+describe('pageStyle frontmatter round-trip', () => {
+  it('survives the squisq-custom-themes codec deep-equal', () => {
+    const theme = clone(THEMES['tech-dark']);
+    theme.id = 'custom-tech';
+    const encoded = writeCustomThemesToFrontmatter([theme]);
+    expect(encoded).toBeDefined();
+    const decoded = readCustomThemesFromFrontmatter({ 'squisq-custom-themes': encoded });
+    expect(decoded).toHaveLength(1);
+    expect(decoded![0].pageStyle).toEqual(theme.pageStyle);
+  });
+});

package/src/__tests__/templateAnnotationParse.test.ts

@@ -57,6 +57,19 @@ describe('Template annotation in Heading parse path', () => {
     if (heading.type !== 'heading') throw new Error('expected heading');
     expect(heading.templateAnnotation).toBeUndefined();
   });
+
+  it('keeps annotation-shaped text inside a code fence as literal code', () => {
+    const source = '```markdown\n## Example {[comparisonBar]}\n{[ ]}\n```';
+    const parsed = parseMarkdown(source);
+
+    expect(parsed.children).toHaveLength(1);
+    expect(parsed.children[0]).toMatchObject({
+      type: 'code',
+      lang: 'markdown',
+      value: '## Example {[comparisonBar]}\n{[ ]}',
+    });
+    expect(stringifyMarkdown(parsed).trim()).toBe(source);
+  });
 });
 
 describe('Quoted values in {[…]} annotations', () => {

package/src/doc/index.ts

@@ -28,6 +28,40 @@ export {
   FRONTMATTER_CUSTOM_THEMES_KEY,
 } from './customThemesFrontmatter.js';
 export { resolveThemeForDoc } from './resolveDocTheme.js';
+export {
+  materializePageSection,
+  materializePageSections,
+  resolvePageStyle,
+} from './page/materializePageSection.js';
+export type {
+  MaterializePageSectionOptions,
+  MaterializePageSectionsOptions,
+  PageTransformHints,
+} from './page/materializePageSection.js';
+export { isTemplatedPageBlock, resolvePageBlock } from './page/resolvePageBlock.js';
+export type { ResolvedPageBlock } from './page/resolvePageBlock.js';
+export { sectionExtractors } from './page/sectionExtractors.js';
+export type {
+  PageSectionContext,
+  PageSectionDraft,
+  SectionExtractor,
+} from './page/sectionExtractors.js';
+export type {
+  PageMedia,
+  PageRichText,
+  PageSection,
+  PageSectionDiagnostic,
+  PageSectionItem,
+  PageSectionMaterialization,
+  PageSectionSource,
+  PageSpatialKind,
+} from './page/PageSection.js';
+export {
+  PAGE_BASE_CSS,
+  buildPageCss,
+  buildPageCssVars,
+  pageStyleDataAttributes,
+} from './pageCss.js';
 export { resolveAudioMapping, scoreTextSimilarity } from './audioMapping.js';
 export { applyNarrationTiming, type NarrationResolution } from './applyNarrationTiming.js';
 export {

package/src/doc/markdownToDoc.ts

@@ -40,7 +40,7 @@ import type {
   MarkdownNode,
   HtmlNode,
 } from '../markdown/types.js';
-import { extractPlainText } from '../markdown/utils.js';
+import { extractPlainText, readFrontmatterThemeId } from '../markdown/utils.js';
 import { coerceAnnotationValues, type CoercedBlockMeta } from '../markdown/annotationCoercion.js';
 import { estimateReadingTime } from '../timing/readingTime.js';
 import { resolveTemplateName, isContainerTemplate } from './templates/index.js';
@@ -600,6 +600,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
 
   const customTemplates = readCustomTemplatesFromFrontmatter(markdownDoc.frontmatter);
   const customThemes = readCustomThemesFromFrontmatter(markdownDoc.frontmatter);
+  const themeId = readFrontmatterThemeId(markdownDoc.frontmatter);
   const doc: Doc = {
     articleId,
     duration: currentTime,
@@ -609,6 +610,7 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
     },
     ...(captions ? { captions } : {}),
     ...(markdownDoc.frontmatter ? { frontmatter: markdownDoc.frontmatter } : {}),
+    ...(themeId ? { themeId } : {}),
     ...(customTemplates ? { customTemplates } : {}),
     ...(customThemes ? { customThemes } : {}),
     ...(diagnostics.length > 0 ? { diagnostics } : {}),

package/src/doc/materializeBlockLayers.ts

@@ -6,7 +6,7 @@
  * failure policy, and diagnostics cannot drift by render mode.
  */
 
-import type { Block, Layer } from '../schemas/Doc.js';
+import type { Block, Layer, MermaidLayer, Position } from '../schemas/Doc.js';
 import type {
   DocBlock,
   PersistentLayerConfig,
@@ -16,6 +16,7 @@ import type {
 import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
 import type { Theme } from '../schemas/Theme.js';
 import type { ViewportConfig } from '../schemas/Viewport.js';
+import type { MarkdownCodeBlock } from '../markdown/types.js';
 import { createTemplateContext, isTemplateBlock } from '../schemas/BlockTemplates.js';
 import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
 import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
@@ -62,7 +63,12 @@ export type LayerMaterializationDiagnostic =
     };
 
 /** Identifies which path produced a materialized layer graph. */
-export type LayerMaterializationSource = 'authored' | 'template' | 'fallback' | 'empty';
+export type LayerMaterializationSource =
+  | 'authored'
+  | 'template'
+  | 'rich-content'
+  | 'fallback'
+  | 'empty';
 
 /**
  * Complete result from {@link materializeBlockLayers}. Failures are data, not
@@ -145,9 +151,10 @@ export function materializeBlockLayersWithRuntime(
 
   const existingLayers = (block as Block).layers;
   if (existingLayers && existingLayers.length > 0 && !isTemplateBlock(block)) {
+    const layers = appendMermaidLayers(cloneData(existingLayers), block as Block, theme, viewport);
     return {
       layers: injectPersistentLayers(
-        cloneData(existingLayers),
+        layers,
         block,
         theme,
         effectivePersistentLayers,
@@ -158,15 +165,16 @@ export function materializeBlockLayersWithRuntime(
   }
 
   if (!isTemplateBlock(block)) {
+    const layers = appendMermaidLayers([], block as Block, theme, viewport);
     return {
       layers: injectPersistentLayers(
-        [],
+        layers,
         block,
         theme,
         effectivePersistentLayers,
         runtime.expandedPersistentLayers,
       ),
-      source: 'empty',
+      source: layers.length > 0 ? 'rich-content' : 'empty',
     };
   }
 
@@ -181,9 +189,10 @@ export function materializeBlockLayersWithRuntime(
       runtime.applyRenderStyle !== false
         ? applyRenderStyleToLayers(execution.layers, block as Block, theme)
         : execution.layers;
+    const layers = appendMermaidLayers(styledLayers, block as Block, theme, viewport);
     return {
       layers: injectPersistentLayers(
-        styledLayers,
+        layers,
         block,
         theme,
         effectivePersistentLayers,
@@ -195,22 +204,29 @@ export function materializeBlockLayersWithRuntime(
 
   const diagnostic = toLayerMaterializationDiagnostic(block.template, execution);
   if ((options.failureMode ?? 'fallback') === 'empty') {
+    const layers = appendMermaidLayers([], block as Block, theme, viewport);
     return {
       layers: injectPersistentLayers(
-        [],
+        layers,
         block,
         theme,
         effectivePersistentLayers,
         runtime.expandedPersistentLayers,
       ),
-      source: 'empty',
+      source: layers.length > 0 ? 'rich-content' : 'empty',
       diagnostic,
     };
   }
 
+  const fallbackLayers = appendMermaidLayers(
+    fallbackBlockLayers(block, context, diagnostic.message),
+    block as Block,
+    theme,
+    viewport,
+  );
   return {
     layers: injectPersistentLayers(
-      fallbackBlockLayers(block, context, diagnostic.message),
+      fallbackLayers,
       block,
       theme,
       effectivePersistentLayers,
@@ -221,6 +237,151 @@ export function materializeBlockLayersWithRuntime(
   };
 }
 
+interface LayerRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Mermaid fences are explicit author intent and never inferred from other code. */
+function mermaidSources(block: Block): string[] {
+  return (block.contents ?? [])
+    .filter(
+      (node): node is MarkdownCodeBlock =>
+        node.type === 'code' && node.lang?.trim().toLowerCase() === 'mermaid',
+    )
+    .map((node) => node.value)
+    .filter((source) => source.trim().length > 0);
+}
+
+function resolvePositionValue(value: number | string | undefined, dimension: number): number {
+  if (value === undefined) return 0;
+  if (typeof value === 'number') return value;
+  const percent = value.match(/^\s*(-?\d+(?:\.\d+)?)%\s*$/);
+  if (percent) return (Number(percent[1]) / 100) * dimension;
+  const numeric = Number.parseFloat(value);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+function positionRect(
+  position: Position,
+  viewport: ViewportConfig,
+  fallbackWidth: number,
+  fallbackHeight: number,
+): LayerRect {
+  const width = position.width
+    ? resolvePositionValue(position.width, viewport.width)
+    : fallbackWidth;
+  const height = position.height
+    ? resolvePositionValue(position.height, viewport.height)
+    : fallbackHeight;
+  let x = resolvePositionValue(position.x, viewport.width);
+  let y = resolvePositionValue(position.y, viewport.height);
+  const anchor = position.anchor ?? 'top-left';
+  if (anchor === 'center') {
+    x -= width / 2;
+    y -= height / 2;
+  } else {
+    if (anchor.endsWith('right')) x -= width;
+    if (anchor.startsWith('bottom')) y -= height;
+  }
+  return { x, y, width, height };
+}
+
+function overlapArea(a: LayerRect, b: LayerRect): number {
+  const width = Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x));
+  const height = Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
+  return width * height;
+}
+
+/**
+ * Pick the least-obstructed media region when a template already owns the
+ * slide. Background shapes/paths are deliberately ignored; text and existing
+ * rich media are what the Mermaid inset must avoid.
+ */
+function mermaidRegion(layers: readonly Layer[], viewport: ViewportConfig): LayerRect {
+  const occupied = layers
+    .filter((layer) => layer.type !== 'shape' && layer.type !== 'path' && layer.type !== 'mermaid')
+    .map((layer) =>
+      positionRect(
+        layer.position,
+        viewport,
+        layer.type === 'text' ? viewport.width * 0.45 : viewport.width * 0.5,
+        layer.type === 'text' ? viewport.height * 0.2 : viewport.height * 0.55,
+      ),
+    );
+  if (occupied.length === 0) {
+    return {
+      x: viewport.width * 0.06,
+      y: viewport.height * 0.08,
+      width: viewport.width * 0.88,
+      height: viewport.height * 0.84,
+    };
+  }
+
+  const candidates: LayerRect[] = [
+    {
+      x: viewport.width * 0.52,
+      y: viewport.height * 0.12,
+      width: viewport.width * 0.44,
+      height: viewport.height * 0.76,
+    },
+    {
+      x: viewport.width * 0.04,
+      y: viewport.height * 0.12,
+      width: viewport.width * 0.44,
+      height: viewport.height * 0.76,
+    },
+    {
+      x: viewport.width * 0.15,
+      y: viewport.height * 0.53,
+      width: viewport.width * 0.7,
+      height: viewport.height * 0.41,
+    },
+  ];
+  return candidates.reduce((best, candidate) => {
+    const score = occupied.reduce((sum, rect) => sum + overlapArea(candidate, rect), 0);
+    const bestScore = occupied.reduce((sum, rect) => sum + overlapArea(best, rect), 0);
+    return score < bestScore ? candidate : best;
+  });
+}
+
+/** Add every Mermaid fence as a responsive rich-media layer. */
+function appendMermaidLayers(
+  layers: Layer[],
+  block: Block,
+  theme: Theme,
+  viewport: ViewportConfig,
+): Layer[] {
+  const sources = mermaidSources(block);
+  if (sources.length === 0 || layers.some((layer) => layer.type === 'mermaid')) return layers;
+
+  const region = mermaidRegion(layers, viewport);
+  const columns = sources.length === 1 ? 1 : 2;
+  const rows = Math.ceil(sources.length / columns);
+  const gap = Math.min(viewport.width, viewport.height) * 0.018;
+  const width = (region.width - gap * (columns - 1)) / columns;
+  const height = (region.height - gap * (rows - 1)) / rows;
+  const mermaidLayers: MermaidLayer[] = sources.map((source, index) => ({
+    id: `${block.id}-mermaid-${index + 1}`,
+    type: 'mermaid',
+    position: {
+      x: region.x + (index % columns) * (width + gap),
+      y: region.y + Math.floor(index / columns) * (height + gap),
+      width,
+      height,
+    },
+    content: {
+      source,
+      background: theme.colors.backgroundLight,
+      foreground: theme.colors.text,
+      padding: Math.max(12, Math.round(Math.min(width, height) * 0.025)),
+    },
+  }));
+  return [...layers, ...mermaidLayers];
+}
+
 function executeTemplateMaterialization(
   templateBlock: TemplateBlock,
   context: TemplateContext,