@bendyline/squisq-react 1.1.2 → 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.1.2",
+  "version": "1.3.0",
   "description": "React component library for doc playback, block rendering, and media layers",
   "license": "MIT",
   "author": "Bendyline",
@@ -31,20 +31,21 @@
   ],
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "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": {
-      "import": "./dist/standalone-source.js",
-      "types": "./dist/standalone-source.d.ts"
+      "types": "./dist/standalone-source.d.ts",
+      "import": "./dist/standalone-source.js"
     }
   },
   "scripts": {
     "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.2.2"
+    "@bendyline/squisq": "1.4.0"
   },
   "devDependencies": {
     "@types/react": "18.3.28",

package/src/DocPlayer.tsx

@@ -25,9 +25,11 @@
 import { Fragment, useRef, useState, useEffect, useCallback, useMemo } from 'react';
 import type { Doc, Block, TextLayer, StartBlockConfig, DocBlock } from '@bendyline/squisq/schemas';
 import { isTemplateBlock, getCaptionAtTime } from '@bendyline/squisq/schemas';
-import type { Theme } from '@bendyline/squisq/schemas';
+import type { SurfaceScheme, Theme } from '@bendyline/squisq/schemas';
+import { applySurface } from '@bendyline/squisq/schemas';
 import { BlockRenderer } from './BlockRenderer';
 import { CaptionOverlay } from './CaptionOverlay';
+import { useAutoSurface } from './hooks/useAutoSurface';
 import { useAudioSync } from './hooks/useAudioSync';
 import { useDocPlayback } from './hooks/useDocPlayback';
 import { useViewportOrientation } from './hooks/useViewportOrientation';
@@ -162,6 +164,13 @@ interface DocPlayerProps {
   forceViewport?: ViewportConfig;
   /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
   theme?: Theme;
+  /**
+   * Optional surface scheme (light / dark paper) overlaid on top of the
+   * theme's colors. Passed through to the underlying LinearDocView when
+   * `displayMode === 'linear'`; otherwise overlaid onto the theme that
+   * renders the player's SVG blocks.
+   */
+  surface?: SurfaceScheme | 'auto';
   /**
    * Display mode for the player.
    * - `'video'` (default) — Traditional video playback with play/pause, scrub bar, auto-advance.
@@ -197,6 +206,7 @@ export function DocPlayer({
   forceViewport,
   displayMode = 'video',
   theme,
+  surface,
   captionStyle = 'standard',
 }: DocPlayerProps) {
   const isSlideshowMode = displayMode === 'slideshow';
@@ -275,6 +285,15 @@ export function DocPlayer({
     [renderMode, toggle, isPlaying, isSlideshowMode, isLinearMode],
   );
 
+  // Resolve surface (light/dark paper) and apply it to the theme before
+  // handing off to downstream renderers. Orthogonal to the editorial theme.
+  const autoSurface = useAutoSurface(surface === 'auto');
+  const resolvedSurface = surface === 'auto' ? autoSurface : surface;
+  const effectiveTheme = useMemo(() => {
+    const base = theme ?? DEFAULT_THEME;
+    return resolvedSurface ? applySurface(base, resolvedSurface) : base;
+  }, [theme, resolvedSurface]);
+
   // Doc playback hook - pass viewport for responsive template expansion
   const {
     currentBlock,
@@ -288,14 +307,14 @@ export function DocPlayer({
     nextBlock: _nextBlock,
     prevBlock: _prevBlock,
     blocks: expandedBlocks,
-  } = useDocPlayback(script, currentTime, activeViewport, renderMode, theme);
+  } = useDocPlayback(script, currentTime, activeViewport, renderMode, effectiveTheme);
 
   // Expand cover block (startBlock) if present - uses active viewport
   const coverBlock = useMemo((): Block | null => {
     const startBlockConfig = script.startBlock as StartBlockConfig | undefined;
     if (!startBlockConfig) return null;
 
-    const context = createTemplateContext(theme ?? DEFAULT_THEME, 0, 1, activeViewport);
+    const context = createTemplateContext(effectiveTheme, 0, 1, activeViewport);
     const layers = expandCoverBlock(startBlockConfig, context);
 
     return {
@@ -305,7 +324,7 @@ export function DocPlayer({
       audioSegment: -1,
       layers,
     };
-  }, [script.startBlock, activeViewport, theme]);
+  }, [script.startBlock, activeViewport, effectiveTheme]);
 
   // Render-mode cover block control: allows Playwright to force-show the cover block
   const [coverForced, setCoverForced] = useState(false);
@@ -314,14 +333,25 @@ export function DocPlayer({
   const [coverGraceActive, setCoverGraceActive] = useState(false);
   const coverGraceTimer = useRef<ReturnType<typeof setTimeout>>();
   const coverWasShowing = useRef(false);
+  // Track whether playback has ever been initiated — prevents the cover block
+  // from re-appearing when paused at currentTime === 0 (e.g., no audio source).
+  const hasPlayedOnce = useRef(false);
 
   // Track when cover is showing at rest (before play)
-  const atRest = !!(coverBlock && !isPlaying && currentTime === 0 && !renderMode && !autoPlay);
+  const atRest = !!(
+    coverBlock &&
+    !isPlaying &&
+    currentTime === 0 &&
+    !hasPlayedOnce.current &&
+    !renderMode &&
+    !autoPlay
+  );
   if (atRest) coverWasShowing.current = true;
 
   useEffect(() => {
     if (isPlaying && coverWasShowing.current && coverBlock && !renderMode) {
       coverWasShowing.current = false;
+      hasPlayedOnce.current = true;
       setCoverGraceActive(true);
       // Intentionally no cleanup: if coverBlock's memoized reference changes
       // mid-grace (e.g., due to a preview re-render), clearing the timer would
@@ -344,7 +374,7 @@ export function DocPlayer({
     coverBlock &&
     (coverForced ||
       coverGraceActive ||
-      (!isPlaying && currentTime === 0 && !renderMode && !autoPlay));
+      (!isPlaying && currentTime === 0 && !hasPlayedOnce.current && !renderMode && !autoPlay));
 
   // Auto-play if enabled (wait for audio to be ready)
   // Use a ref to track if we've already auto-played to avoid repeating on every render
@@ -785,7 +815,13 @@ export function DocPlayer({
           overflow: 'hidden',
         }}
       >
-        <LinearDocView doc={script} basePath={basePath} viewport={activeViewport} />
+        <LinearDocView
+          doc={script}
+          basePath={basePath}
+          viewport={activeViewport}
+          theme={theme}
+          surface={surface}
+        />
       </div>
     );
   }
@@ -857,7 +893,7 @@ export function DocPlayer({
             enabled={captionsEnabled && (renderMode || isPlaying || currentTime > 0)}
             fontSize={16}
             captionStyle={activeCaptionStyle}
-            theme={theme}
+            theme={effectiveTheme}
             viewport={activeViewport}
           />
         )}

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

@@ -18,9 +18,15 @@
  */
 
 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 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';
@@ -42,8 +48,35 @@ export interface LinearDocViewProps {
   className?: string;
   /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
   theme?: Theme;
+  /**
+   * Optional surface scheme (light / dark paper) overlaid on top of the
+   * theme's colors. Orthogonal to `theme` — a theme picks editorial
+   * identity, a surface picks the paper. Pass `'auto'` to follow the
+   * user's OS `prefers-color-scheme`, a `SurfaceScheme` object to force a
+   * specific surface, or omit to use the theme's built-in colors.
+   */
+  surface?: SurfaceScheme | 'auto';
+  /**
+   * Use tight padding + a wider content column. The default layout is
+   * designed for a reading surface with breathing room (720px column,
+   * 24×16px padding). Short conversational snippets like chat replies
+   * benefit from a much tighter layout. Set to `true` to render with
+   * minimal padding and no max-width cap so the content hugs its
+   * container.
+   */
+  thinMargins?: boolean;
+  /**
+   * How images inside the doc should be sized. `'inline'` (default)
+   * flows them at natural size up to the column width; `'thumbnail'`
+   * constrains each image to a 100×100 box with aspect-preserving
+   * containment — use for chat history and other dense surfaces where
+   * full-size images would dominate the layout.
+   */
+  imageDisplayMode?: ImageDisplayMode;
 }
 
+export type ImageDisplayMode = 'inline' | 'thumbnail';
+
 // ── Helpers ────────────────────────────────────────────────────────
 
 /**
@@ -136,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',
             }}
           >
@@ -216,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[];
@@ -249,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 };
@@ -257,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'] };
     }
@@ -269,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 {};
   }
@@ -294,26 +433,31 @@ export function LinearDocView({
   viewport,
   className,
   theme,
+  surface,
+  thinMargins = false,
+  imageDisplayMode = 'inline',
 }: LinearDocViewProps) {
   const activeViewport = viewport ?? VIEWPORT_PRESETS.landscape;
   const totalBlocks = useMemo(() => countAll(doc.blocks), [doc.blocks]);
+  const autoSurface = useAutoSurface(surface === 'auto');
+  const resolvedSurface: SurfaceScheme | undefined = surface === 'auto' ? autoSurface : surface;
 
-  const renderContext: RenderContext = useMemo(
-    () => ({
-      theme: theme ?? DEFAULT_THEME,
+  const renderContext: RenderContext = useMemo(() => {
+    const baseTheme = theme ?? DEFAULT_THEME;
+    return {
+      theme: resolvedSurface ? applySurface(baseTheme, resolvedSurface) : baseTheme,
       viewport: activeViewport,
       totalBlocks,
-    }),
-    [activeViewport, totalBlocks, theme],
-  );
+    };
+  }, [activeViewport, totalBlocks, theme, resolvedSurface]);
 
   const activeTheme = renderContext.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 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 (
@@ -321,19 +465,28 @@ export function LinearDocView({
       className={`squisq-linear ${className || ''}`}
       style={{
         width: '100%',
-        height: '100%',
-        overflowY: 'auto',
+        // Thin-margins mode is the "embedded in someone else's container"
+        // signal (chat bubble, sidebar preview). Fit to content there so
+        // the host's bubble doesn't render a tall empty box when the doc
+        // is short. Standalone mode keeps height:100% for full-viewport
+        // scrolling.
+        height: thinMargins ? 'auto' : '100%',
+        overflowY: thinMargins ? 'visible' : 'auto',
         overflowX: 'hidden',
         background: bgColor,
       }}
     >
       <div
-        className="squisq-linear-content squisq-md"
+        className={`squisq-linear-content squisq-md${thinMargins ? ' squisq-linear-content--thin' : ''}${imageDisplayMode === 'thumbnail' ? ' squisq-linear-content--thumbnail-images' : ''}`}
         style={
           {
-            maxWidth: '720px',
-            margin: '0 auto',
-            padding: '24px 16px',
+            // Thin-margins mode drops the 720px reading column + generous
+            // page padding (right for standalone docs) in favor of a tight
+            // layout that hugs its container (right for chat bubbles and
+            // sidebar previews).
+            maxWidth: thinMargins ? 'none' : '720px',
+            margin: thinMargins ? '0' : '0 auto',
+            padding: thinMargins ? '0' : '24px 16px',
             lineHeight: lineHt,
             fontSize: '16px',
             fontFamily: bodyFont,
@@ -376,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 {
@@ -414,6 +578,14 @@ export function LinearDocView({
             border-radius: 6px;
             margin: 0.5em 0;
           }
+          .squisq-linear-content--thumbnail-images img {
+            max-width: 100px;
+            max-height: 100px;
+            width: auto;
+            height: auto;
+            object-fit: contain;
+            display: block;
+          }
           .squisq-linear-content strong {
             font-weight: 700;
           }