@bendyline/squisq-react 1.2.0 → 1.3.0

package/dist/types.d.ts

@@ -26,8 +26,12 @@ export type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
  * - `'linear'` — Long-scrolling document view. Renders the full markdown as
  *   readable HTML with template-annotated sections shown as inline SVG cards.
  *   No audio, no timeline, no controls — just a scrollable page.
+ * - `'page'` — Plain semantic HTML preview matching what the
+ *   `markdownDocToPlainHtml` export produces. No SquisqPlayer, no SVG
+ *   cards — just `<h1>`/`<p>`/`<ul>` etc. inside a sandboxed iframe.
+ *   Use when you want a WYSIWYG view of the simple HTML export.
  */
-export type DisplayMode = 'video' | 'slideshow' | 'linear';
+export type DisplayMode = 'video' | 'slideshow' | 'linear' | 'page';
 /**
  * Caption display style.
  *

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA0JH,6CAA6C;AAC7C,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA8JH,6CAA6C;AAC7C,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-react",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "React component library for doc playback, block rendering, and media layers",
   "license": "MIT",
   "author": "Bendyline",
@@ -34,7 +34,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./styles": "./src/styles/doc-animations.css",
+    "./styles": "./src/styles/index.css",
     "./standalone": "./dist/squisq-player.global.js",
     "./standalone-source": {
       "types": "./dist/standalone-source.d.ts",
@@ -45,6 +45,7 @@
     "build": "tsup && tsup --config tsup.standalone.config.ts && node scripts/generate-standalone-source.mjs",
     "build:esm": "tsup",
     "build:standalone": "tsup --config tsup.standalone.config.ts && node scripts/generate-standalone-source.mjs",
+    "dev": "npm run build:standalone && concurrently -n js,dts -c blue,gray -r \"tsup --watch --no-dts --no-clean\" \"tsup --watch --dts-only --no-clean\"",
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
@@ -52,7 +53,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.3.0"
+    "@bendyline/squisq": "1.4.0"
   },
   "devDependencies": {
     "@types/react": "18.3.28",

package/src/InlineAudioPlayer.tsx

@@ -0,0 +1,46 @@
+/**
+ * InlineAudioPlayer
+ *
+ * Small inline HTML5 audio player for `<audio>` tags embedded directly in
+ * a markdown document — e.g. a narration recording the user wants to
+ * audition in the editor. Resolves the `src` through `MediaContext` so a
+ * container-backed `audio/foo.webm` path returns a playable blob URL.
+ *
+ * Deliberately thin: native browser controls, no autoplay. The
+ * MarkdownRenderer swaps this in for raw `<audio>` htmlElements; the
+ * editor-react Tiptap audio node reuses it for its NodeView.
+ */
+import { useMediaUrl } from './hooks/MediaContext.js';
+
+export interface InlineAudioPlayerProps {
+  /** Source path — resolved through MediaContext when relative. */
+  src: string;
+  /** Base path used when no MediaProvider is in context. */
+  basePath?: string;
+  /** Whether to show native controls. Defaults to true. */
+  controls?: boolean;
+  /** `preload` attribute passthrough. Defaults to `'metadata'`. */
+  preload?: 'none' | 'metadata' | 'auto';
+  /** Extra className on the wrapper. */
+  className?: string;
+}
+
+export function InlineAudioPlayer({
+  src,
+  basePath = '',
+  controls = true,
+  preload = 'metadata',
+  className,
+}: InlineAudioPlayerProps) {
+  const resolvedSrc = useMediaUrl(src, basePath);
+
+  if (!resolvedSrc) return null;
+
+  return (
+    <span className={`squisq-inline-audio-player ${className ?? ''}`.trim()}>
+      <audio src={resolvedSrc} controls={controls} preload={preload} />
+    </span>
+  );
+}
+
+export default InlineAudioPlayer;

package/src/InlineVideoPlayer.tsx

@@ -0,0 +1,70 @@
+/**
+ * InlineVideoPlayer
+ *
+ * Small inline HTML5 video player for `<video>` tags embedded directly in
+ * a markdown document — e.g. a recording dropped into the doc by the
+ * recorder. Resolves the `src` through `MediaContext` (same path
+ * `VideoLayer` uses) so a container-backed `audio/foo.webm` or
+ * `video/foo.mp4` resolves to a blob URL instead of 404-ing on the
+ * filesystem path.
+ *
+ * Deliberately thin: native browser controls, intrinsic aspect ratio,
+ * no autoplay. The MarkdownRenderer swaps this in for a raw `<video>`
+ * htmlElement; the editor-react Tiptap video node uses the same
+ * component for its NodeView.
+ */
+import { useMediaUrl } from './hooks/MediaContext.js';
+
+export interface InlineVideoPlayerProps {
+  /** Source path — resolved through MediaContext when relative. */
+  src: string;
+  /** Base path used when no MediaProvider is in context. */
+  basePath?: string;
+  /** Optional explicit width (pixels or CSS length). */
+  width?: number | string;
+  /** Optional explicit height (pixels or CSS length). */
+  height?: number | string;
+  /** Optional poster image src — also resolved through MediaContext. */
+  poster?: string;
+  /** Whether to show native controls. Defaults to true. */
+  controls?: boolean;
+  /** `preload` attribute passthrough. Defaults to `'metadata'`. */
+  preload?: 'none' | 'metadata' | 'auto';
+  /** Extra className on the wrapper. */
+  className?: string;
+}
+
+export function InlineVideoPlayer({
+  src,
+  basePath = '',
+  width,
+  height,
+  poster,
+  controls = true,
+  preload = 'metadata',
+  className,
+}: InlineVideoPlayerProps) {
+  const resolvedSrc = useMediaUrl(src, basePath);
+  // Always call the hook (Rules of Hooks); only use the result if a poster
+  // was actually requested. Empty input → fallback path which we discard.
+  const resolvedPoster = useMediaUrl(poster ?? '', basePath);
+  const posterUrl = poster ? resolvedPoster : undefined;
+
+  if (!resolvedSrc) return null;
+
+  return (
+    <span className={`squisq-inline-video-player ${className ?? ''}`.trim()}>
+      <video
+        src={resolvedSrc}
+        poster={posterUrl}
+        controls={controls}
+        preload={preload}
+        width={width}
+        height={height}
+        playsInline
+      />
+    </span>
+  );
+}
+
+export default InlineVideoPlayer;

package/src/LinearDocView.tsx

@@ -21,7 +21,12 @@ import { useMemo } from 'react';
 import { useAutoSurface } from './hooks/useAutoSurface';
 import type { Doc, Block, DocBlock } from '@bendyline/squisq/schemas';
 import type { ViewportConfig } from '@bendyline/squisq/schemas';
-import { applySurface, type SurfaceScheme, type Theme } from '@bendyline/squisq/schemas';
+import {
+  applySurface,
+  resolveFontFamily,
+  type SurfaceScheme,
+  type Theme,
+} from '@bendyline/squisq/schemas';
 import { VIEWPORT_PRESETS } from '@bendyline/squisq/schemas';
 import { getLayers, hasTemplate, DEFAULT_THEME } from '@bendyline/squisq/doc';
 import type { RenderContext } from '@bendyline/squisq/doc';
@@ -164,23 +169,21 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
       {/* Render the heading (if present — preamble has no sourceHeading) */}
       {block.sourceHeading && !isAnnotated && <MarkdownRenderer nodes={[block.sourceHeading]} />}
 
-      {/* Annotated block: render SVG card */}
+      {/* Annotated block: render SVG card.
+          The heading is intentionally *not* duplicated above the card —
+          every template card renders its own title layer internally, so
+          a separate `squisq-linear-card-label` only made the heading
+          appear twice in the linear view. The card also drops its
+          rounded border + drop shadow so it reads as a continuation of
+          the surrounding page rather than a chrome'd preview. */}
       {isAnnotated && visualBlock && (
         <div className="squisq-linear-card">
-          {/* Optional heading label above the card */}
-          {block.sourceHeading && (
-            <div className="squisq-linear-card-label squisq-md">
-              <MarkdownRenderer nodes={[block.sourceHeading]} />
-            </div>
-          )}
           <div
             className="squisq-linear-card-svg"
             style={{
               width: '100%',
               aspectRatio: `${viewport.width} / ${viewport.height}`,
               overflow: 'hidden',
-              borderRadius: '8px',
-              boxShadow: '0 2px 8px rgba(0, 0, 0, 0.12)',
               marginBottom: '1em',
             }}
           >
@@ -244,6 +247,83 @@ function extractListItems(contents?: MarkdownBlockNode[]): string[] {
   return items;
 }
 
+/** First image discovered in a block's body, with any explicit
+ *  dimensions captured (set by `<img width>` / `<img height>` in raw
+ *  HTML — markdown shorthand has no syntax for dimensions). */
+interface FirstImage {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * Find the first image referenced anywhere in block contents — both
+ * markdown shorthand `![alt](url)` (type `image`) and raw HTML `<img>`
+ * tags (type `htmlBlock`/`htmlInline`). The WYSIWYG editor emits the
+ * HTML form whenever a user resizes an image (markdown shorthand has no
+ * width syntax), so missing that path silently breaks every resized
+ * image in the linear view.
+ */
+function extractFirstImage(contents: MarkdownBlockNode[] | undefined): FirstImage | null {
+  if (!contents || contents.length === 0) return null;
+
+  function fromHtml(nodes: unknown[]): FirstImage | null {
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') continue;
+      const n = node as Record<string, unknown>;
+      if (n.type === 'htmlElement' && n.tagName === 'img') {
+        const attrs = n.attributes as Record<string, string> | undefined;
+        if (attrs && typeof attrs.src === 'string' && attrs.src) {
+          return {
+            src: attrs.src,
+            alt: typeof attrs.alt === 'string' ? attrs.alt : '',
+            width: parseDim(attrs.width),
+            height: parseDim(attrs.height),
+          };
+        }
+      }
+      if (Array.isArray(n.children)) {
+        const found = fromHtml(n.children);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  function walk(node: unknown): FirstImage | null {
+    if (!node || typeof node !== 'object') return null;
+    const n = node as Record<string, unknown>;
+    if (n.type === 'image' && typeof n.url === 'string' && n.url) {
+      return { src: n.url, alt: typeof n.alt === 'string' ? n.alt : '' };
+    }
+    if ((n.type === 'htmlBlock' || n.type === 'htmlInline') && Array.isArray(n.htmlChildren)) {
+      const found = fromHtml(n.htmlChildren);
+      if (found) return found;
+    }
+    if (Array.isArray(n.children)) {
+      for (const child of n.children) {
+        const found = walk(child);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  for (const node of contents) {
+    const found = walk(node);
+    if (found) return found;
+  }
+  return null;
+}
+
+/** Parse a `width`/`height` HTML attribute to a positive number. */
+function parseDim(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = parseFloat(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
 /** Extract table data (headers, rows, alignment) from block contents. */
 function extractTableData(contents?: MarkdownBlockNode[]): {
   headers: string[];
@@ -277,7 +357,7 @@ function getTemplateDefaults(
   switch (templateName) {
     case 'statHighlight':
       return { stat: headingText, description: bodyText || headingText };
-    case 'quoteBlock':
+    case 'quote':
     case 'fullBleedQuote':
     case 'pullQuote':
       return { quote: bodyText || headingText };
@@ -285,7 +365,7 @@ function getTemplateDefaults(
       return { fact: headingText, explanation: bodyText || headingText };
     case 'comparisonBar':
       return { leftLabel: 'A', leftValue: 60, rightLabel: 'B', rightValue: 40 };
-    case 'listBlock': {
+    case 'list': {
       const items = extractListItems(contents);
       return { items: items.length > 0 ? items : ['Item 1', 'Item 2', 'Item 3'] };
     }
@@ -297,6 +377,37 @@ function getTemplateDefaults(
       const tableData = extractTableData(contents);
       return tableData ?? { headers: ['Column'], rows: [['Data']] };
     }
+    case 'imageWithCaption': {
+      // The template requires `imageSrc` — without it the image layer
+      // renders a broken `<img src=undefined>`. Pull the first image
+      // out of the block's body (markdown shorthand or HTML <img>) and
+      // use the heading as a caption fallback so a bare `# Title
+      // [Image with Caption]` block renders something sensible.
+      const img = extractFirstImage(contents);
+      if (!img) return { caption: headingText };
+      return {
+        imageSrc: img.src,
+        imageAlt: img.alt || headingText,
+        caption: headingText,
+      };
+    }
+    case 'leftFeature':
+    case 'rightFeature': {
+      // Feature blocks pair an image with the heading + the first
+      // paragraph of body text. Both inputs come from the section's
+      // contents — the image via the same scan used by imageWithCaption,
+      // the body text via the plain-text extractor that's already in
+      // scope here.
+      const img = extractFirstImage(contents);
+      return {
+        imageSrc: img?.src ?? '',
+        imageAlt: img?.alt || headingText,
+        imageWidth: img?.width,
+        imageHeight: img?.height,
+        title: headingText,
+        body: bodyText,
+      };
+    }
     default:
       return {};
   }
@@ -345,8 +456,8 @@ export function LinearDocView({
   const textColor = activeTheme.colors.text;
   const mutedColor = activeTheme.colors.textMuted;
   const primaryColor = activeTheme.colors.primary;
-  const bodyFont = activeTheme.typography.bodyFontFamily;
-  const titleFont = activeTheme.typography.titleFontFamily;
+  const bodyFont = resolveFontFamily(activeTheme.typography.bodyFont, 'system-ui, sans-serif');
+  const titleFont = resolveFontFamily(activeTheme.typography.titleFont, 'Georgia, serif');
   const lineHt = activeTheme.typography.lineHeight ?? 1.7;
 
   return (
@@ -418,6 +529,17 @@ export function LinearDocView({
             margin-bottom: 0.3em;
           }
           .squisq-linear-content a {
+            /* Blend the theme's primary toward the body text color so
+               links stay theme-flavored but always have enough contrast
+               against the background. Some themes (e.g. Gezellig) pick a
+               mid-tone primary that's nearly invisible on a dark page
+               without this lift. */
+            color: color-mix(in srgb, var(--squisq-linear-primary) 65%, var(--squisq-linear-text));
+            text-decoration: underline;
+            text-decoration-thickness: 1px;
+            text-underline-offset: 2px;
+          }
+          .squisq-linear-content a:hover {
             color: var(--squisq-linear-primary);
           }
           .squisq-linear-content code {

package/src/MarkdownRenderer.tsx

@@ -21,8 +21,12 @@ import type {
   MarkdownListItem,
   MarkdownTableRow,
   MarkdownTableCell,
+  HtmlNode,
+  HtmlElement,
 } from '@bendyline/squisq/markdown';
 import { useMediaUrl } from './hooks/MediaContext';
+import { InlineVideoPlayer } from './InlineVideoPlayer.js';
+import { InlineAudioPlayer } from './InlineAudioPlayer.js';
 
 // ── Props ──────────────────────────────────────────────────────────
 
@@ -118,12 +122,23 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
         );
 
       case 'htmlInline':
+        // Fast path: no <video>/<audio> in the subtree → use the original
+        // rawHtml passthrough (preserves arbitrary HTML for custom embeds).
+        if (!containsMediaTag(node.htmlChildren)) {
+          return (
+            <span
+              key={key}
+              className="squisq-md-html-inline"
+              dangerouslySetInnerHTML={{ __html: node.rawHtml }}
+            />
+          );
+        }
+        // Otherwise reconstruct the subtree as React so <video>/<audio>
+        // go through MediaContext-aware player components.
         return (
-          <span
-            key={key}
-            className="squisq-md-html-inline"
-            dangerouslySetInnerHTML={{ __html: node.rawHtml }}
-          />
+          <span key={key} className="squisq-md-html-inline">
+            {renderHtmlNodes(node.htmlChildren, `${key}h`)}
+          </span>
         );
 
       case 'footnoteReference':
@@ -231,12 +246,23 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       return renderTable(node.children, node.align, key);
 
     case 'htmlBlock':
+      // Fast path: no <video>/<audio> → preserve the existing rawHtml
+      // passthrough so arbitrary HTML embeds still survive verbatim.
+      if (!containsMediaTag(node.htmlChildren)) {
+        return (
+          <div
+            key={key}
+            className="squisq-md-html-block"
+            dangerouslySetInnerHTML={{ __html: node.rawHtml }}
+          />
+        );
+      }
+      // Otherwise reconstruct subtree as React so <video>/<audio>
+      // route through the player components and resolve via MediaContext.
       return (
-        <div
-          key={key}
-          className="squisq-md-html-block"
-          dangerouslySetInnerHTML={{ __html: node.rawHtml }}
-        />
+        <div key={key} className="squisq-md-html-block">
+          {renderHtmlNodes(node.htmlChildren, `${key}h`)}
+        </div>
       );
 
     case 'math':
@@ -377,6 +403,126 @@ function MdImage({ src, alt, title }: { src: string; alt: string; title?: string
   return <img className="squisq-md-image" src={resolved} alt={alt} title={title} />;
 }
 
+// ── Raw-HTML walker (intercepts <video>/<audio>) ─────────────────
+
+/** True when the htmlElement subtree contains a tag we want to swap
+ *  for a React component. Cheap recursive scan — lets us keep the
+ *  `dangerouslySetInnerHTML` fast path for everything else. */
+function containsMediaTag(nodes: HtmlNode[]): boolean {
+  for (const node of nodes) {
+    if (node.type !== 'htmlElement') continue;
+    if (node.tagName === 'video' || node.tagName === 'audio') return true;
+    if (containsMediaTag(node.children)) return true;
+  }
+  return false;
+}
+
+/** A pragmatic shortlist of HTML attributes the raw-HTML walker
+ *  passes through to React when reconstructing a non-media element.
+ *  Anything outside this list is silently dropped — the media-tag
+ *  fast path means most authors will never hit this code, so we
+ *  keep the surface narrow to avoid React warnings about unknown
+ *  attributes. */
+const PASSTHROUGH_ATTRS: Record<string, string> = {
+  // common
+  class: 'className',
+  id: 'id',
+  title: 'title',
+  style: 'style',
+  // media-adjacent (used when video/audio appear inside other wrappers)
+  width: 'width',
+  height: 'height',
+  // anchor
+  href: 'href',
+  target: 'target',
+  rel: 'rel',
+};
+
+function reactPropsFromAttrs(attrs: Record<string, string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(attrs)) {
+    const propName = PASSTHROUGH_ATTRS[name];
+    if (!propName) continue;
+    if (propName === 'style') {
+      // We can't safely parse arbitrary `style="..."` strings without
+      // an HTML parser; preserve as a data attribute so authors can
+      // see it survived round-trip without crashing React.
+      out['data-style'] = value;
+      continue;
+    }
+    out[propName] = value;
+  }
+  return out;
+}
+
+function renderHtmlElement(el: HtmlElement, key: string): React.ReactNode {
+  if (el.tagName === 'video') {
+    return (
+      <InlineVideoPlayer
+        key={key}
+        src={el.attributes.src ?? ''}
+        width={el.attributes.width}
+        height={el.attributes.height}
+        poster={el.attributes.poster}
+        // The `controls` attribute is a boolean — present means true,
+        // even if its value is an empty string.
+        controls={'controls' in el.attributes}
+        preload={
+          el.attributes.preload === 'none' ||
+          el.attributes.preload === 'metadata' ||
+          el.attributes.preload === 'auto'
+            ? el.attributes.preload
+            : undefined
+        }
+      />
+    );
+  }
+  if (el.tagName === 'audio') {
+    return (
+      <InlineAudioPlayer
+        key={key}
+        src={el.attributes.src ?? ''}
+        controls={'controls' in el.attributes}
+        preload={
+          el.attributes.preload === 'none' ||
+          el.attributes.preload === 'metadata' ||
+          el.attributes.preload === 'auto'
+            ? el.attributes.preload
+            : undefined
+        }
+      />
+    );
+  }
+
+  const Tag = el.tagName as keyof JSX.IntrinsicElements;
+  const props = reactPropsFromAttrs(el.attributes);
+  if (el.selfClosing) {
+    return <Tag key={key} {...props} />;
+  }
+  return (
+    <Tag key={key} {...props}>
+      {renderHtmlNodes(el.children, `${key}c`)}
+    </Tag>
+  );
+}
+
+function renderHtmlNodes(nodes: HtmlNode[], keyPrefix: string): React.ReactNode[] {
+  return nodes.map((node, i) => {
+    const key = `${keyPrefix}${i}`;
+    switch (node.type) {
+      case 'htmlElement':
+        return renderHtmlElement(node, key);
+      case 'htmlText':
+        return <Fragment key={key}>{node.value}</Fragment>;
+      case 'htmlComment':
+        // Comments don't render in React; ignore.
+        return null;
+      default:
+        return null;
+    }
+  });
+}
+
 // ── Main Component ─────────────────────────────────────────────────
 
 /**

package/src/SocialCaptionOverlay.tsx

@@ -17,6 +17,7 @@
 import { useMemo } from 'react';
 import type { CaptionTrack, CaptionPhrase, ViewportConfig } from '@bendyline/squisq/schemas';
 import type { Theme } from '@bendyline/squisq/schemas';
+import { resolveFontFamily } from '@bendyline/squisq/schemas';
 
 /** Target words per visible chunk. */
 const TARGET_CHUNK_SIZE = 4;
@@ -196,8 +197,8 @@ export function SocialCaptionOverlay({
 
   // Theme-derived styling
   const primaryColor = theme?.colors?.primary ?? '#5b9bd5';
-  const fontFamily = theme?.typography?.titleFontFamily
-    ? `"${theme.typography.titleFontFamily}", system-ui, sans-serif`
+  const fontFamily = theme?.typography?.titleFont
+    ? resolveFontFamily(theme.typography.titleFont, '"PT Serif", Georgia, serif')
     : '"PT Serif", Georgia, serif';
 
   // Scale font to viewport — aim for ~5.5% of viewport height