@bendyline/squisq 2.0.0 → 2.1.0

package/src/doc/templates/__tests__/listBlock.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { createTemplateContext } from '../../../schemas/BlockTemplates.js';
+import type { TextLayer } from '../../../schemas/Doc.js';
+import { DEFAULT_THEME } from '../../../schemas/themeLibrary.js';
+import { VIEWPORT_PRESETS } from '../../../schemas/Viewport.js';
+import { listBlock } from '../listBlock.js';
+
+const ITEMS = [
+  'We launched the scripting platform for Minecraft, which was essential for launching new categories of content for Minecraft (add-ons)',
+  "I spec'ed and largely built the Minecraft Creator Tools suite, including a website for beginning to advanced creators and set of NPM commands and tools.",
+  'I manage and craft the Minecraft samples and documentation suite',
+  'I produce and create the Minecraft Creator Channel on YouTube',
+];
+
+describe('listBlock', () => {
+  it('reserves vertical space for wrapped list items', () => {
+    const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    const layers = listBlock(
+      {
+        template: 'list',
+        id: 'minecraft-platform',
+        duration: 10,
+        audioSegment: 0,
+        title: 'Minecraft Platform',
+        items: ITEMS,
+      },
+      context,
+    );
+    const itemLayers = layers.filter(
+      (layer): layer is TextLayer => layer.type === 'text' && /^item-\d+$/.test(layer.id),
+    );
+    const markerLayers = layers.filter(
+      (layer): layer is TextLayer => layer.type === 'text' && /^item-\d+-marker$/.test(layer.id),
+    );
+    const yPositions = itemLayers.map((layer) => parseFloat(String(layer.position.y)));
+
+    expect(itemLayers).toHaveLength(4);
+    expect(markerLayers).toHaveLength(4);
+    expect(yPositions[0]).toBe(34);
+
+    // The marker has its own right-aligned column, while all body lines are
+    // rendered by one layer beginning after that column (a hanging indent).
+    expect(markerLayers[0]!.content.text).toBe('1.');
+    expect(markerLayers[0]!.content.style.textAlign).toBe('right');
+    expect(itemLayers[0]!.content.text).toBe(ITEMS[0]);
+    const markerRightPx =
+      (parseFloat(String(markerLayers[0]!.position.x)) / 100) * context.viewport.width +
+      Number(markerLayers[0]!.position.width);
+    const bodyLeftPx =
+      (parseFloat(String(itemLayers[0]!.position.x)) / 100) * context.viewport.width;
+    expect(bodyLeftPx).toBeGreaterThan(markerRightPx);
+
+    // The first two entries wrap to two lines. Their following baselines
+    // therefore advance by two line-heights plus the inter-item gap.
+    const fontSize = itemLayers[0]!.content.style.fontSize;
+    const twoLineAdvance = ((2 * fontSize * 1.2 + 18) / context.viewport.height) * 100;
+    expect(yPositions[1]! - yPositions[0]!).toBeCloseTo(twoLineAdvance);
+    expect(yPositions[2]! - yPositions[1]!).toBeCloseTo(twoLineAdvance);
+
+    // The third entry fits on one line, so the final advance is compact.
+    const oneLineAdvance = ((fontSize * 1.2 + 18) / context.viewport.height) * 100;
+    expect(yPositions[3]! - yPositions[2]!).toBeCloseTo(oneLineAdvance);
+  });
+});

package/src/doc/templates/listBlock.ts

@@ -19,6 +19,43 @@ import {
 } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
+const LIST_ITEM_LINE_HEIGHT = 1.2;
+const LIST_ITEM_GAP_PX = 18;
+
+/**
+ * Mirror the renderer's character-based wrapping closely enough to reserve
+ * vertical space for each independently positioned text layer.
+ */
+function estimateWrappedLineCount(text: string, fontSize: number, maxWidth: number): number {
+  if (!text.trim()) return 1;
+
+  const charsPerLine = Math.floor(maxWidth / (fontSize * 0.5));
+  if (charsPerLine <= 0) return 1;
+
+  let lineCount = 0;
+  let currentLineLength = 0;
+
+  for (const word of text.split(/\s+/)) {
+    const testLineLength = currentLineLength ? currentLineLength + 1 + word.length : word.length;
+
+    if (testLineLength <= charsPerLine) {
+      currentLineLength = testLineLength;
+      continue;
+    }
+
+    if (currentLineLength) lineCount += 1;
+
+    let remainingLength = word.length;
+    while (remainingLength > charsPerLine) {
+      lineCount += 1;
+      remainingLength -= charsPerLine;
+    }
+    currentLineLength = remainingLength;
+  }
+
+  return Math.max(1, lineCount + (currentLineLength ? 1 : 0));
+}
+
 export function listBlock(input: ListBlockInput, context: TemplateContext): Layer[] {
   const { title, accentImage } = input;
   // `items` is required by the schema, but malformed / partially-authored
@@ -66,8 +103,9 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
   // defensive against future edits to the accent-layout types).
   const centerX = parseFloat(accentLayout.textCenterX);
   const widthPct = parseFloat(accentLayout.textWidth);
-  const leftX =
-    Number.isFinite(centerX) && Number.isFinite(widthPct) ? `${centerX - widthPct / 2}%` : '8%';
+  const leftPct =
+    Number.isFinite(centerX) && Number.isFinite(widthPct) ? centerX - widthPct / 2 : 8;
+  const leftX = `${leftPct}%`;
 
   // Title if provided
   const startY = title ? 34 : 26;
@@ -95,28 +133,49 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
     });
   }
 
-  // Stack items with a fixed compact gap rather than stretching them
-  // across the available band. Distributing items across (startY → 80%)
-  // left big vertical gaps for short lists and made the slide read as a
-  // sparse menu instead of a tight enumeration; conversely a bare
-  // line-height gap read as a cramped paragraph — 18px of air keeps each
-  // entry its own line without breaking the group.
-  //
-  // Spacing = item line-height (34px base × 1.2) + 18px gap, expressed
-  // as % of the 1080px design canvas (~5.4%). Wrapped items push the
-  // next entry down via their own line-height, so this sets the
-  // minimum baseline-to-baseline distance for unwrapped items.
-  const LIST_ITEM_BASE_PX = 34;
-  const LIST_ITEM_LINE_HEIGHT = 1.2;
-  const LIST_ITEM_GAP_PX = 18;
-  const DESIGN_HEIGHT_PX = 1080;
-  const spacing =
-    ((LIST_ITEM_BASE_PX * LIST_ITEM_LINE_HEIGHT + LIST_ITEM_GAP_PX) / DESIGN_HEIGHT_PX) * 100;
+  // Render the number and body in separate columns. The body is therefore a
+  // single text layer whose wrapped lines all share the same x coordinate,
+  // producing a hanging indent instead of wrapping underneath the number.
+  const textWidthPx = (Number.isFinite(widthPct) ? widthPct / 100 : 0.85) * context.viewport.width;
+  const markerText = `${items.length}.`;
+  const markerWidthPx = Math.max(itemFontSize, markerText.length * itemFontSize * 0.5);
+  const markerGapPx = itemFontSize * 0.35;
+  const bodyIndentPx = markerWidthPx + markerGapPx;
+  const bodyLeftX = `${leftPct + (bodyIndentPx / context.viewport.width) * 100}%`;
+  const bodyWidthPx = Math.max(itemFontSize, textWidthPx - bodyIndentPx);
+  let itemY = startY;
 
   // List items with staggered animation
   for (let i = 0; i < items.length; i++) {
-    const y = startY + spacing * i;
-    const itemText = `${i + 1}.  ${items[i]}`;
+    const itemText = items[i]!;
+    const lineCount = estimateWrappedLineCount(itemText, itemFontSize, bodyWidthPx);
+    const animation = themedEntrance(context, 'text', {
+      type: 'fadeIn',
+      duration: 0.8,
+      delay: 0.3 + 0.3 * i,
+    });
+
+    layers.push({
+      type: 'text',
+      id: `item-${i}-marker`,
+      content: {
+        text: `${i + 1}.`,
+        style: {
+          fontSize: itemFontSize,
+          fontFamily: getThemeFont(context, 'body'),
+          color: theme.colors.text,
+          textAlign: 'right',
+          lineHeight: LIST_ITEM_LINE_HEIGHT,
+          shadow: shouldUseShadow(context),
+        },
+      },
+      position: {
+        x: leftX,
+        y: adjustY(`${itemY}%`, accentLayout),
+        width: markerWidthPx,
+      },
+      animation,
+    });
 
     layers.push({
       type: 'text',
@@ -128,21 +187,20 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'left',
-          lineHeight: 1.2,
+          lineHeight: LIST_ITEM_LINE_HEIGHT,
           shadow: shouldUseShadow(context),
         },
       },
       position: {
-        x: leftX,
-        y: adjustY(`${y}%`, accentLayout),
-        width: accentLayout.textWidth,
+        x: bodyLeftX,
+        y: adjustY(`${itemY}%`, accentLayout),
+        width: bodyWidthPx,
       },
-      animation: themedEntrance(context, 'text', {
-        type: 'fadeIn',
-        duration: 0.8,
-        delay: 0.3 + 0.3 * i,
-      }),
+      animation,
     });
+
+    const itemHeightPx = lineCount * itemFontSize * LIST_ITEM_LINE_HEIGHT;
+    itemY += ((itemHeightPx + LIST_ITEM_GAP_PX) / context.viewport.height) * 100;
   }
 
   return layers;

package/src/schemas/Doc.ts

@@ -381,7 +381,8 @@ export type Layer =
   | MapLayer
   | VideoLayer
   | TableLayer
-  | TreeLayer;
+  | TreeLayer
+  | MermaidLayer;
 
 interface BaseLayer {
   /** Unique identifier for this layer */
@@ -759,6 +760,26 @@ export interface TreeLayerStyle {
   fileIcon?: string;
 }
 
+/**
+ * Mermaid diagram layer — renders an authored `mermaid` code fence through
+ * the official Mermaid runtime while keeping the fence source authoritative.
+ * Like video/table/tree layers, the browser renderer hosts the diagram in an
+ * SVG `<foreignObject>` so it participates in slide layout and frame capture.
+ */
+export interface MermaidLayer extends BaseLayer {
+  type: 'mermaid';
+  content: {
+    /** Complete Mermaid source, excluding the Markdown fence delimiters. */
+    source: string;
+    /** Theme-derived panel color behind the generated SVG. */
+    background?: string;
+    /** Theme-derived foreground used by loading/error states. */
+    foreground?: string;
+    /** Inner panel padding in pixels. */
+    padding?: number;
+  };
+}
+
 /**
  * Available map tile styles from free/open-source providers.
  */

package/src/schemas/PageStyle.ts

@@ -0,0 +1,213 @@
+/**
+ * Page Style — the theme's art-direction layer for Page (linear) mode.
+ *
+ * Slides render through fixed-viewport SVG templates; pages render through
+ * a small closed vocabulary of variable-height HTML section layouts
+ * (`PageSectionKind`). A `ThemePageStyle` is how a theme art-directs that
+ * page rendition: it picks a design family, sets page-wide tokens
+ * (column widths, spacing, dividers, hero treatment, image framing …),
+ * and can override how individual section kinds or block templates map
+ * onto the section vocabulary.
+ *
+ * Design principles (mirrors the rest of the Theme schema):
+ * - Fully JSON-serializable — rides the `squisq-custom-themes` frontmatter
+ *   codec unchanged.
+ * - Closed enums everywhere so renderers can switch exhaustively and the
+ *   validator can reject typos.
+ * - Optional on `Theme`; `resolvePageStyle`/`defaultPageStyle` derive a
+ *   complete style from existing theme fields when absent, so legacy and
+ *   customizer themes keep working without edits.
+ */
+
+// ============================================
+// Section vocabulary
+// ============================================
+
+/**
+ * The closed set of page section layouts. Every block template maps onto
+ * one of these kinds (see `doc/page/sectionExtractors.ts`); themes may
+ * remap via `ThemePageStyle.sections` / `.templates`.
+ */
+export const PAGE_SECTION_KINDS = [
+  'hero',
+  'banner',
+  'stat-band',
+  'quote-band',
+  'feature-split',
+  'media-figure',
+  'gallery',
+  'callout',
+  'card-grid',
+  'item-list',
+  'timeline-rail',
+  'table-section',
+  'canvas-embed',
+  'prose',
+  'footer',
+] as const;
+
+export type PageSectionKind = (typeof PAGE_SECTION_KINDS)[number];
+
+/** Relative visual weight of a section within the page. */
+export type PageEmphasis = 'lead' | 'strong' | 'standard' | 'quiet';
+
+/** Which background treatment a section sits on. */
+export type PageBackground = 'base' | 'alternate' | 'accent' | 'media';
+
+// ============================================
+// Design families + tokens
+// ============================================
+
+/**
+ * Broad page design personalities. A family selects the structural
+ * skeleton (how sections compose); tokens parameterize it per theme.
+ */
+export const PAGE_DESIGN_FAMILIES = [
+  'clean',
+  'editorial',
+  'brutalist',
+  'terminal',
+  'cinematic',
+  'documentary',
+  'organic',
+  'soft',
+] as const;
+
+export type PageDesignFamily = (typeof PAGE_DESIGN_FAMILIES)[number];
+
+/** How headings announce themselves across the page. */
+export interface PageHeadingTreatment {
+  /** Small label above headings: none, plain kicker, "01 —" numbering, or a mono tag. */
+  eyebrow: 'none' | 'kicker' | 'numbered' | 'mono-tag';
+  /** Overall heading size register. */
+  scale: 'regular' | 'display' | 'oversized';
+  /** Optional case transform for headings/eyebrows. */
+  case?: 'none' | 'uppercase';
+  /** Optional decoration under headings. */
+  underline?: 'none' | 'accent-bar' | 'full-rule';
+}
+
+/**
+ * Page-wide design tokens. Structural CSS reads these via
+ * `--squisq-page-*` custom properties (see `doc/pageCss.ts`).
+ */
+export interface PageTokens {
+  /** Reading-column max width in px (prose, callouts, quotes). */
+  contentMaxWidth: number;
+  /** Wide-band inner max width in px (figures, tables, feature splits). */
+  wideMaxWidth: number;
+  /** Vertical rhythm between sections. */
+  sectionSpacing: 'compact' | 'comfortable' | 'generous';
+  /** Corner radius for cards, media frames, panels (px). */
+  cornerRadius: number;
+  /** Divider treatment between sections. */
+  divider: 'none' | 'gap-only' | 'hairline' | 'thick-rule' | 'double-rule' | 'dotted';
+  /** How section backgrounds vary down the page. */
+  backgroundRhythm: 'flat' | 'alternate' | 'accent-bands' | 'tinted-panels';
+  /** Hero (cover/title) composition. */
+  heroStyle: 'stacked' | 'split' | 'full-bleed' | 'letterbox' | 'oversized-type';
+  /** Heading voice across the page. */
+  headingTreatment: PageHeadingTreatment;
+  /** Frame treatment for photographic media. */
+  imageFraming: 'flush' | 'rounded' | 'bordered' | 'polaroid' | 'letterboxed' | 'circle-accent';
+  /** Shadow language for elevated elements. */
+  shadow: 'none' | 'soft' | 'crisp' | 'heavy';
+  /** Decoration on quote sections. */
+  quoteMark: 'none' | 'oversized-glyph' | 'accent-bar';
+  /** Treatment of large stat numerals. */
+  numeralStyle: 'plain' | 'oversized' | 'boxed' | 'mono';
+  /** Optional page background pattern. */
+  pattern?: 'none' | 'dots' | 'grid' | 'diagonal' | 'noise';
+}
+
+// ============================================
+// Overrides + accent rotation
+// ============================================
+
+/**
+ * A theme's override for one section kind or one block template —
+ * remap the kind, force a variant, adjust emphasis/background, or pass
+ * freeform scalar hints the section renderer understands.
+ */
+export interface PageSectionOverride {
+  kind?: PageSectionKind;
+  variant?: string;
+  emphasis?: PageEmphasis;
+  background?: PageBackground;
+  /** Freeform scalar hints (e.g. `dropCap: true`, `frame: "terminal"`). */
+  hints?: Record<string, string | number | boolean>;
+}
+
+/** How named color schemes rotate across accent-bearing sections. */
+export interface PageAccentRotation {
+  strategy: 'primary-only' | 'cycle' | 'alternate-two' | 'none';
+  /**
+   * ColorScheme names (keys of `theme.colorSchemes`) to rotate through.
+   * Defaults to all schemes in insertion order.
+   */
+  schemes?: string[];
+}
+
+// ============================================
+// ThemePageStyle
+// ============================================
+
+/**
+ * The complete page art direction for a theme. Optional on `Theme`;
+ * `defaultPageStyle(theme)` derives one from existing theme fields.
+ */
+export interface ThemePageStyle {
+  family: PageDesignFamily;
+  tokens: PageTokens;
+  /** Per-section-kind overrides. */
+  sections?: Partial<Record<PageSectionKind, PageSectionOverride>>;
+  /** Per-template overrides (canonical template ids); win over `sections`. */
+  templates?: Record<string, PageSectionOverride>;
+  accentRotation: PageAccentRotation;
+}
+
+// ============================================
+// Enum sets (shared by the validator + defaults)
+// ============================================
+
+export const PAGE_SECTION_SPACINGS = ['compact', 'comfortable', 'generous'] as const;
+export const PAGE_DIVIDERS = [
+  'none',
+  'gap-only',
+  'hairline',
+  'thick-rule',
+  'double-rule',
+  'dotted',
+] as const;
+export const PAGE_BACKGROUND_RHYTHMS = [
+  'flat',
+  'alternate',
+  'accent-bands',
+  'tinted-panels',
+] as const;
+export const PAGE_HERO_STYLES = [
+  'stacked',
+  'split',
+  'full-bleed',
+  'letterbox',
+  'oversized-type',
+] as const;
+export const PAGE_EYEBROWS = ['none', 'kicker', 'numbered', 'mono-tag'] as const;
+export const PAGE_HEADING_SCALES = ['regular', 'display', 'oversized'] as const;
+export const PAGE_HEADING_CASES = ['none', 'uppercase'] as const;
+export const PAGE_HEADING_UNDERLINES = ['none', 'accent-bar', 'full-rule'] as const;
+export const PAGE_IMAGE_FRAMINGS = [
+  'flush',
+  'rounded',
+  'bordered',
+  'polaroid',
+  'letterboxed',
+  'circle-accent',
+] as const;
+export const PAGE_SHADOWS = ['none', 'soft', 'crisp', 'heavy'] as const;
+export const PAGE_QUOTE_MARKS = ['none', 'oversized-glyph', 'accent-bar'] as const;
+export const PAGE_NUMERAL_STYLES = ['plain', 'oversized', 'boxed', 'mono'] as const;
+export const PAGE_PATTERNS = ['none', 'dots', 'grid', 'diagonal', 'noise'] as const;
+export const PAGE_EMPHASES = ['lead', 'strong', 'standard', 'quiet'] as const;
+export const PAGE_BACKGROUNDS = ['base', 'alternate', 'accent', 'media'] as const;
+export const PAGE_ACCENT_STRATEGIES = ['primary-only', 'cycle', 'alternate-two', 'none'] as const;

package/src/schemas/Theme.ts

@@ -23,6 +23,7 @@
 import type { LayoutHints } from './LayoutStrategy.js';
 import type { AnimationType, ImageTreatment, TransitionType } from './Doc.js';
 import type { PersistentLayerConfig } from './BlockTemplates.js';
+import type { ThemePageStyle } from './PageStyle.js';
 import { THEME_SCHEMA_VERSION } from './themeConstants.js';
 import { validateTheme } from './themeValidator.js';
 import { cloneAndFreezeData } from '../internal/immutable.js';
@@ -236,6 +237,12 @@ export interface Theme {
   colorSchemes: Record<string, ThemeColorScheme>;
   /** Optional persistent layers baked into the theme */
   persistentLayers?: PersistentLayerConfig;
+  /**
+   * Optional page art direction for Page (linear) mode. When absent,
+   * `resolvePageStyle`/`defaultPageStyle` derive one from the fields above,
+   * so legacy themes render pages without declaring this.
+   */
+  pageStyle?: ThemePageStyle;
 }
 
 // ============================================

package/src/schemas/index.ts

@@ -5,6 +5,8 @@ export * from './Media.js';
 export * from './BlockTemplates.js';
 export * from './CustomTemplates.js';
 export * from './Theme.js';
+export * from './PageStyle.js';
+export * from './pageStyleDefaults.js';
 export * from './themeLibrary.js';
 export * from './themeValidator.js';
 export * from './themeCompile.js';