@bendyline/squisq-react 1.0.2 → 1.0.3

package/dist/types.d.ts

@@ -28,6 +28,21 @@ export type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
  *   No audio, no timeline, no controls — just a scrollable page.
  */
 export type DisplayMode = 'video' | 'slideshow' | 'linear';
+/**
+ * Caption display style.
+ *
+ * - `'standard'` — Traditional broadcast-style captions: small white text
+ *   on a semi-transparent black badge at the top of the player.
+ * - `'social'` — Social media-style (Instagram/TikTok): large centered words
+ *   showing 3-5 words at a time with the active word highlighted in the
+ *   theme's primary color. Font and colors pulled from the active theme.
+ */
+export type CaptionStyle = 'standard' | 'social';
+/**
+ * Caption display mode — combines enable/disable with style selection.
+ * The CC button cycles through: off → standard → social → off.
+ */
+export type CaptionMode = 'off' | 'standard' | 'social';
 /** Slide navigation actions for slideshow display mode */
 export interface SlideNavActions {
     /** Navigate to the next slide */
@@ -47,6 +62,8 @@ export interface PlaybackState {
     docProgress: number;
     hasCaptions: boolean;
     captionsEnabled: boolean;
+    /** Current caption display mode (off, standard, social). */
+    captionMode: CaptionMode;
     isFullscreen?: boolean;
     /** Current audio segment index (0-based) */
     currentSegmentIndex: number;
@@ -61,6 +78,8 @@ export interface PlaybackActions {
     restart: () => void;
     seekTo: (time: number) => void;
     setCaptionsEnabled: (enabled: boolean) => void;
+    /** Cycle caption mode: off → standard → social → off */
+    cycleCaptionMode: () => void;
     toggleFullscreen?: () => void;
 }
 /** Block marker data for the progress bar */

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;AAqIH,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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-react",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "React component library for doc playback, block rendering, and media layers",
   "license": "MIT",
   "author": "Bendyline",
@@ -52,7 +52,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.1.0"
+    "@bendyline/squisq": "1.1.1"
   },
   "devDependencies": {
     "@types/react": "^18.0.0",

package/src/CaptionOverlay.tsx

@@ -2,15 +2,19 @@
  * CaptionOverlay Component
  *
  * Displays closed captions synchronized with audio playback.
- * Captions cross-fade smoothly using CSS transitions on a single
- * persistent element (no mount/unmount flicker).
+ * Supports two styles:
  *
- * The captions are generated by the postprocess-doc command based
- * on article text and audio segment timing.
+ * - `'standard'` (default): Traditional broadcast captions — small white text
+ *   on a semi-transparent black badge at the top of the player.
+ * - `'social'`: Social media-style (Instagram/TikTok) — large centered words
+ *   with the active word highlighted in the theme's primary color.
  */
 
-import type { CaptionTrack } from '@bendyline/squisq/schemas';
+import type { CaptionTrack, ViewportConfig } from '@bendyline/squisq/schemas';
 import { getCaptionAtTime } from '@bendyline/squisq/schemas';
+import type { Theme } from '@bendyline/squisq/schemas';
+import type { CaptionStyle } from './types';
+import { SocialCaptionOverlay } from './SocialCaptionOverlay';
 
 interface CaptionOverlayProps {
   /** Caption track with timestamped phrases */
@@ -19,8 +23,14 @@ interface CaptionOverlayProps {
   currentTime: number;
   /** Whether captions are enabled */
   enabled?: boolean;
-  /** Font size in pixels (default: 16) */
+  /** Font size in pixels for standard style (default: 16) */
   fontSize?: number;
+  /** Caption display style (default: 'standard') */
+  captionStyle?: CaptionStyle;
+  /** Theme for social-style caption colors and fonts */
+  theme?: Theme;
+  /** Viewport config for social-style font scaling */
+  viewport?: ViewportConfig;
 }
 
 export function CaptionOverlay({
@@ -28,9 +38,24 @@ export function CaptionOverlay({
   currentTime,
   enabled = true,
   fontSize = 16,
+  captionStyle = 'standard',
+  theme,
+  viewport,
 }: CaptionOverlayProps) {
-  // Derive caption directly from currentTime -- pure computation, no hooks.
-  // This avoids race conditions between timeupdate events and async state updates.
+  // Delegate to social overlay when that style is active
+  if (captionStyle === 'social') {
+    return (
+      <SocialCaptionOverlay
+        captions={captions}
+        currentTime={currentTime}
+        enabled={enabled}
+        theme={theme}
+        viewport={viewport}
+      />
+    );
+  }
+
+  // Standard caption rendering
   const phrase = enabled && captions ? getCaptionAtTime(captions, currentTime) : null;
   const captionText = phrase?.text ?? null;
 

package/src/DocControlsBottom.tsx

@@ -85,13 +85,19 @@ export function DocControlsBottom({
         {state.currentBlockIndex + 1}/{state.totalBlocks}
       </span>
 
-      {/* Caption toggle */}
+      {/* Caption mode cycle */}
       {state.hasCaptions && (
         <button
-          className={`bottom-ctrl-btn ${state.captionsEnabled ? 'bottom-ctrl-btn--active' : ''}`}
-          onClick={() => actions.setCaptionsEnabled(!state.captionsEnabled)}
-          title={state.captionsEnabled ? 'Hide captions' : 'Show captions'}
-          aria-label={state.captionsEnabled ? 'Hide captions' : 'Show captions'}
+          className={`bottom-ctrl-btn ${state.captionMode !== 'off' ? 'bottom-ctrl-btn--active' : ''}`}
+          onClick={() => actions.cycleCaptionMode()}
+          title={
+            state.captionMode === 'off'
+              ? 'Captions: Off'
+              : state.captionMode === 'standard'
+                ? 'Captions: Standard'
+                : 'Captions: Social'
+          }
+          aria-label="Cycle caption style"
         >
           <svg viewBox="0 0 24 24" fill="currentColor" width="18" height="18">
             <path d="M19 4H5a2 2 0 00-2 2v12a2 2 0 002 2h14a2 2 0 002-2V6a2 2 0 00-2-2zm-8 7H9.5v-.5h-2v3h2V13H11v1a1 1 0 01-1 1H7a1 1 0 01-1-1v-4a1 1 0 011-1h3a1 1 0 011 1v1zm7 0h-1.5v-.5h-2v3h2V13H18v1a1 1 0 01-1 1h-3a1 1 0 01-1-1v-4a1 1 0 011-1h3a1 1 0 011 1v1z" />

package/src/DocControlsOverlay.tsx

@@ -121,27 +121,39 @@ export function DocControlsOverlay({
         {state.currentBlockIndex + 1}/{state.totalBlocks}
       </span>
 
-      {/* Caption toggle button */}
+      {/* Caption mode cycle button: off → standard → social → off */}
       {state.hasCaptions && (
         <button
-          onClick={() => actions.setCaptionsEnabled(!state.captionsEnabled)}
+          onClick={() => actions.cycleCaptionMode()}
           style={{
-            background: state.captionsEnabled ? 'rgba(255,255,255,0.2)' : 'none',
+            background: state.captionMode !== 'off' ? 'rgba(255,255,255,0.2)' : 'none',
             border: 'none',
-            color: state.captionsEnabled ? 'white' : 'rgba(255,255,255,0.5)',
+            color: state.captionMode !== 'off' ? 'white' : 'rgba(255,255,255,0.5)',
             cursor: 'pointer',
             padding: '8px',
             fontSize: '12px',
             display: 'flex',
             alignItems: 'center',
+            gap: '4px',
             borderRadius: '4px',
           }}
-          title={state.captionsEnabled ? 'Hide captions' : 'Show captions'}
-          aria-label={state.captionsEnabled ? 'Hide captions' : 'Show captions'}
+          title={
+            state.captionMode === 'off'
+              ? 'Captions: Off (click for Standard)'
+              : state.captionMode === 'standard'
+                ? 'Captions: Standard (click for Social)'
+                : 'Captions: Social (click to turn off)'
+          }
+          aria-label="Cycle caption style"
         >
           <svg viewBox="0 0 24 24" fill="currentColor" width="18" height="18">
             <path d="M19 4H5a2 2 0 00-2 2v12a2 2 0 002 2h14a2 2 0 002-2V6a2 2 0 00-2-2zm-8 7H9.5v-.5h-2v3h2V13H11v1a1 1 0 01-1 1H7a1 1 0 01-1-1v-4a1 1 0 011-1h3a1 1 0 011 1v1zm7 0h-1.5v-.5h-2v3h2V13H18v1a1 1 0 01-1 1h-3a1 1 0 01-1-1v-4a1 1 0 011-1h3a1 1 0 011 1v1z" />
           </svg>
+          {state.captionMode !== 'off' && (
+            <span style={{ fontSize: '10px', textTransform: 'uppercase', letterSpacing: '0.5px' }}>
+              {state.captionMode === 'standard' ? 'CC' : 'SM'}
+            </span>
+          )}
         </button>
       )}
 

package/src/DocControlsSidebar.tsx

@@ -69,13 +69,19 @@ export function DocControlsSidebar({ state, actions }: DocControlsSidebarProps)
         {state.currentBlockIndex + 1}/{state.totalBlocks}
       </div>
 
-      {/* Caption toggle */}
+      {/* Caption mode cycle */}
       {state.hasCaptions && (
         <button
-          className={`sidebar-ctrl-btn ${state.captionsEnabled ? 'sidebar-ctrl-btn--active' : ''}`}
-          onClick={() => actions.setCaptionsEnabled(!state.captionsEnabled)}
-          title={state.captionsEnabled ? 'Hide captions' : 'Show captions'}
-          aria-label={state.captionsEnabled ? 'Hide captions' : 'Show captions'}
+          className={`sidebar-ctrl-btn ${state.captionMode !== 'off' ? 'sidebar-ctrl-btn--active' : ''}`}
+          onClick={() => actions.cycleCaptionMode()}
+          title={
+            state.captionMode === 'off'
+              ? 'Captions: Off'
+              : state.captionMode === 'standard'
+                ? 'Captions: Standard'
+                : 'Captions: Social'
+          }
+          aria-label="Cycle caption style"
         >
           <svg viewBox="0 0 24 24" fill="currentColor" width="20" height="20">
             <path d="M19 4H5a2 2 0 00-2 2v12a2 2 0 002 2h14a2 2 0 002-2V6a2 2 0 00-2-2zm-8 7H9.5v-.5h-2v3h2V13H11v1a1 1 0 01-1 1H7a1 1 0 01-1-1v-4a1 1 0 011-1h3a1 1 0 011 1v1zm7 0h-1.5v-.5h-2v3h2V13H18v1a1 1 0 01-1 1h-3a1 1 0 01-1-1v-4a1 1 0 011-1h3a1 1 0 011 1v1z" />

package/src/DocPlayer.tsx

@@ -48,6 +48,8 @@ import type {
   PlaybackActions,
   BlockMarker,
   DisplayMode,
+  CaptionStyle,
+  CaptionMode,
   SlideNavActions,
   SquisqWindow,
 } from './types';
@@ -169,6 +171,9 @@ interface DocPlayerProps {
    *   template-annotated sections as inline SVG cards. No audio, no timeline.
    */
   displayMode?: DisplayMode;
+  /** Caption display style (default: 'standard').
+   *  'social' shows large centered words with the active word highlighted. */
+  captionStyle?: CaptionStyle;
 }
 
 export function DocPlayer({
@@ -192,6 +197,7 @@ export function DocPlayer({
   forceViewport,
   displayMode = 'video',
   theme,
+  captionStyle = 'standard',
 }: DocPlayerProps) {
   const isSlideshowMode = displayMode === 'slideshow';
   const isLinearMode = displayMode === 'linear';
@@ -433,7 +439,16 @@ export function DocPlayer({
           });
         });
       };
-      w.getDuration = () => totalDuration;
+      w.getDuration = () => {
+        // When audio is present totalDuration comes from audio segments.
+        // For audio-less docs, compute from block timings instead.
+        if (totalDuration > 0) return totalDuration;
+        if (expandedBlocks.length > 0) {
+          const last = expandedBlocks[expandedBlocks.length - 1];
+          return last.startTime + last.duration;
+        }
+        return 0;
+      };
       // Expose block metadata for testing -- allows tests to find specific templates
       w.getBlocks = () =>
         expandedBlocks.map((s: Block) => ({
@@ -494,14 +509,36 @@ export function DocPlayer({
     // eslint-disable-next-line react-hooks/exhaustive-deps -- script is a stable prop; re-registering on every script change is unnecessary
   }, [renderMode, isDebugMode, seekTo, totalDuration, expandedBlocks, coverBlock]);
 
-  // Captions state: use prop if provided, otherwise default to true
-  const captionsEnabled = captionsEnabledProp !== undefined ? captionsEnabledProp : true;
+  // Caption mode state: cycles through off → standard → social → off
+  // The captionStyle prop sets the default active style; captionsEnabledProp
+  // can override the initial on/off state.
+  const defaultMode: CaptionMode =
+    captionsEnabledProp === false ? 'off' : captionStyle || 'standard';
+  const [captionMode, setCaptionMode] = useState<CaptionMode>(defaultMode);
+
+  // Derive captionsEnabled and active style from the mode
+  const captionsEnabled = captionMode !== 'off';
+  const activeCaptionStyle: CaptionStyle = captionMode === 'social' ? 'social' : 'standard';
+
   const setCaptionsEnabled = useCallback(
     (enabled: boolean) => {
+      // When re-enabling, restore the prop-specified style rather than
+      // always defaulting to 'standard'
+      setCaptionMode(enabled ? captionStyle || 'standard' : 'off');
       onCaptionsToggle?.(enabled);
     },
-    [onCaptionsToggle],
+    [onCaptionsToggle, captionStyle],
   );
+
+  const cycleCaptionMode = useCallback(() => {
+    setCaptionMode((prev) => {
+      const next: CaptionMode =
+        prev === 'off' ? 'standard' : prev === 'standard' ? 'social' : 'off';
+      onCaptionsToggle?.(next !== 'off');
+      return next;
+    });
+  }, [onCaptionsToggle]);
+
   const hasCaptions = script.captions && script.captions.phrases.length > 0;
 
   // Map segment indices to human-readable titles (from sectionHeader blocks)
@@ -518,6 +555,7 @@ export function DocPlayer({
       docProgress,
       hasCaptions: !!hasCaptions,
       captionsEnabled,
+      captionMode,
       isFullscreen,
       currentSegmentIndex: currentSegment,
       currentSegmentName:
@@ -534,6 +572,7 @@ export function DocPlayer({
       docProgress,
       hasCaptions,
       captionsEnabled,
+      captionMode,
       isFullscreen,
       currentSegment,
       segmentTitleMap,
@@ -548,9 +587,10 @@ export function DocPlayer({
       restart,
       seekTo,
       setCaptionsEnabled,
+      cycleCaptionMode,
       toggleFullscreen: onFullscreenToggle,
     }),
-    [toggle, restart, seekTo, setCaptionsEnabled, onFullscreenToggle],
+    [toggle, restart, seekTo, setCaptionsEnabled, cycleCaptionMode, onFullscreenToggle],
   );
 
   // Slide navigation actions for slideshow mode
@@ -803,13 +843,16 @@ export function DocPlayer({
           </div>
         )}
 
-        {/* Caption overlay -- hidden in render mode and when stopped on cover block */}
-        {hasCaptions && !renderMode && (
+        {/* Caption overlay -- shown during playback and in render mode when captions are enabled */}
+        {hasCaptions && (renderMode ? captionsEnabled : true) && (
           <CaptionOverlay
             captions={script.captions}
             currentTime={currentTime}
-            enabled={captionsEnabled && (isPlaying || currentTime > 0)}
+            enabled={captionsEnabled && (renderMode || isPlaying || currentTime > 0)}
             fontSize={16}
+            captionStyle={activeCaptionStyle}
+            theme={theme}
+            viewport={activeViewport}
           />
         )}
 
@@ -850,7 +893,11 @@ export function DocPlayer({
             </div>
             <div>
               <span style={{ color: '#888' }}>time:</span> {currentTime.toFixed(2)}s /{' '}
-              {totalDuration.toFixed(1)}s
+              {totalDuration.toFixed(1)}s{' '}
+              <span style={{ color: '#666' }}>
+                (progress: {(docProgress * 100).toFixed(1)}%, scriptDur:{' '}
+                {script.duration.toFixed(1)})
+              </span>
             </div>
             <div>
               <span style={{ color: '#888' }}>blockTime:</span> {blockTime.toFixed(2)}s /{' '}

package/src/DocPlayerWithSidebar.tsx

@@ -52,6 +52,7 @@ const DEFAULT_STATE: PlaybackState = {
   docProgress: 0,
   hasCaptions: false,
   captionsEnabled: false,
+  captionMode: 'off',
   currentSegmentIndex: 0,
   currentSegmentName: null,
   currentBlock: null,

package/src/DocProgressBar.tsx

@@ -106,7 +106,7 @@ export function DocProgressBar({
           left: 0,
           width: `${state.docProgress * 100}%`,
           height: '6px',
-          background: '#3d5a80',
+          background: '#5b9bd5',
           borderRadius: '3px',
           transition: 'width 0.1s',
         }}
@@ -125,7 +125,7 @@ export function DocProgressBar({
             borderRadius: '50%',
             background:
               marker.index === state.currentBlockIndex ? '#ffffff' : 'rgba(255,255,255,0.5)',
-            border: '2px solid #3d5a80',
+            border: '2px solid #5b9bd5',
             cursor: 'pointer',
             zIndex: 2,
             transition: 'transform 0.15s, background 0.15s',

package/src/LinearDocView.tsx

@@ -55,7 +55,7 @@ export interface LinearDocViewProps {
 function isAnnotatedBlock(block: Block): boolean {
   const annotation = block.sourceHeading?.templateAnnotation;
   if (!annotation) return false;
-  return hasTemplate(annotation.template);
+  return !!annotation.template && hasTemplate(annotation.template);
 }
 
 /**
@@ -103,7 +103,12 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
       duration: 1,
       audioSegment: 0,
       title: headingText,
-      ...getTemplateDefaults(annotation.template, headingText, bodyText, block.contents),
+      ...getTemplateDefaults(
+        annotation.template ?? 'sectionHeader',
+        headingText,
+        bodyText,
+        block.contents,
+      ),
       ...annotation.params,
       ...block.templateOverrides,
     };
@@ -276,6 +281,15 @@ export function LinearDocView({
     [activeViewport, totalBlocks, theme],
   );
 
+  const activeTheme = theme ?? DEFAULT_THEME;
+  const bgColor = activeTheme.colors.background;
+  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 lineHt = activeTheme.typography.lineHeight ?? 1.7;
+
   return (
     <div
       className={`squisq-linear ${className || ''}`}
@@ -284,19 +298,97 @@ export function LinearDocView({
         height: '100%',
         overflowY: 'auto',
         overflowX: 'hidden',
+        background: bgColor,
       }}
     >
       <div
-        className="squisq-linear-content"
-        style={{
-          maxWidth: '720px',
-          margin: '0 auto',
-          padding: '24px 16px',
-          lineHeight: 1.7,
-          fontSize: '16px',
-          color: 'var(--squisq-text, #1f2937)',
-        }}
+        className="squisq-linear-content squisq-md"
+        style={
+          {
+            maxWidth: '720px',
+            margin: '0 auto',
+            padding: '24px 16px',
+            lineHeight: lineHt,
+            fontSize: '16px',
+            fontFamily: bodyFont,
+            color: textColor,
+            // CSS custom properties for MarkdownRenderer / nested elements
+            '--squisq-linear-title-font': titleFont,
+            '--squisq-linear-body-font': bodyFont,
+            '--squisq-linear-text': textColor,
+            '--squisq-linear-muted': mutedColor,
+            '--squisq-linear-primary': primaryColor,
+            '--squisq-linear-bg': bgColor,
+          } as React.CSSProperties
+        }
       >
+        {/* Theme-aware typography and layout for document mode */}
+        <style>{`
+          .squisq-linear-content h1,
+          .squisq-linear-content h2,
+          .squisq-linear-content h3,
+          .squisq-linear-content h4,
+          .squisq-linear-content h5,
+          .squisq-linear-content h6 {
+            font-family: var(--squisq-linear-title-font);
+            color: var(--squisq-linear-text);
+            margin-top: 1.2em;
+            margin-bottom: 0.4em;
+          }
+          .squisq-linear-content h1 { font-size: 2em; }
+          .squisq-linear-content h2 { font-size: 1.5em; }
+          .squisq-linear-content h3 { font-size: 1.25em; }
+          .squisq-linear-content p {
+            margin-bottom: 0.75em;
+          }
+          .squisq-linear-content ul,
+          .squisq-linear-content ol {
+            padding-left: 2em;
+            margin-bottom: 0.75em;
+          }
+          .squisq-linear-content li {
+            margin-bottom: 0.3em;
+          }
+          .squisq-linear-content a {
+            color: var(--squisq-linear-primary);
+          }
+          .squisq-linear-content code {
+            color: var(--squisq-linear-primary);
+            font-size: 0.9em;
+            padding: 0.15em 0.3em;
+            border-radius: 3px;
+            background: rgba(128, 128, 128, 0.15);
+          }
+          .squisq-linear-content pre {
+            padding: 1em;
+            border-radius: 6px;
+            background: rgba(0, 0, 0, 0.2);
+            overflow-x: auto;
+            margin-bottom: 0.75em;
+          }
+          .squisq-linear-content pre code {
+            padding: 0;
+            background: none;
+          }
+          .squisq-linear-content blockquote {
+            border-left: 3px solid var(--squisq-linear-muted);
+            color: var(--squisq-linear-muted);
+            padding-left: 1em;
+            margin-left: 0;
+            margin-bottom: 0.75em;
+          }
+          .squisq-linear-content hr {
+            border: none;
+            border-top: 1px solid var(--squisq-linear-muted);
+            margin: 1.5em 0;
+          }
+          .squisq-linear-content strong {
+            font-weight: 700;
+          }
+          .squisq-linear-content em {
+            font-style: italic;
+          }
+        `}</style>
         {doc.blocks.map((block, i) => (
           <BlockSection
             key={block.id}