@bendyline/squisq-react 1.1.2 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-react",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "React component library for doc playback, block rendering, and media layers",
   "license": "MIT",
   "author": "Bendyline",
@@ -31,14 +31,14 @@
   ],
   "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",
     "./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": {
@@ -52,7 +52,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.2.2"
+    "@bendyline/squisq": "1.3.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/LinearDocView.tsx

@@ -18,9 +18,10 @@
  */
 
 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, 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 +43,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 ────────────────────────────────────────────────────────
 
 /**
@@ -294,18 +322,23 @@ 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;
@@ -321,19 +354,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,
@@ -414,6 +456,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;
           }

package/src/MarkdownRenderer.tsx

@@ -40,8 +40,25 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
   return nodes.map((node, i) => {
     const key = `${keyPrefix}i${i}`;
     switch (node.type) {
-      case 'text':
-        return <Fragment key={key}>{node.value}</Fragment>;
+      case 'text': {
+        // Soft breaks (newlines without two trailing spaces) become \n in
+        // text nodes. HTML collapses \n to whitespace, which loses the visual
+        // line break the author wanted, so render <br> for each newline.
+        if (!node.value.includes('\n')) {
+          return <Fragment key={key}>{node.value}</Fragment>;
+        }
+        const parts = node.value.split('\n');
+        return (
+          <Fragment key={key}>
+            {parts.map((part, j) => (
+              <Fragment key={j}>
+                {j > 0 && <br />}
+                {part}
+              </Fragment>
+            ))}
+          </Fragment>
+        );
+      }
 
       case 'emphasis':
         return (
@@ -138,6 +155,20 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
           </span>
         );
 
+      case 'mention':
+        return (
+          <span
+            key={key}
+            className="squisq-md-mention mention"
+            data-mention="true"
+            data-kind={node.targetKind}
+            data-id={node.targetId}
+            data-label={node.displayName}
+          >
+            @{node.displayName}
+          </span>
+        );
+
       default:
         return null;
     }

package/src/__tests__/LinearDocView.test.tsx

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { render } from '@testing-library/react';
 import { LinearDocView } from '../LinearDocView';
 import type { Doc, Block } from '@bendyline/squisq/schemas';
+import { DARK_SURFACE, DEFAULT_THEME, LIGHT_SURFACE } from '@bendyline/squisq/schemas';
 import type {
   MarkdownBlockNode,
   MarkdownInlineNode,
@@ -177,4 +178,38 @@ describe('LinearDocView', () => {
     expect(container.querySelector('[data-block-id="alpha"]')).toBeTruthy();
     expect(container.querySelector('[data-block-id="beta"]')).toBeTruthy();
   });
+
+  it('uses the theme background by default', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('hi'))] })]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    const el = container.querySelector('.squisq-linear') as HTMLElement;
+    expect(el.style.background).toBeTruthy();
+    // DEFAULT_THEME has a specific background; applying LIGHT_SURFACE below
+    // must produce a different value to prove override is working.
+    expect(el.style.background).not.toBe(LIGHT_SURFACE.background);
+  });
+
+  it('light surface overlays the theme background', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('hi'))] })]);
+    const { container } = render(
+      <LinearDocView doc={doc} theme={DEFAULT_THEME} surface={LIGHT_SURFACE} />,
+    );
+    const el = container.querySelector('.squisq-linear') as HTMLElement;
+    // React inline style background may round-trip as hex or rgb; compare the
+    // colour-normalized value by mounting a plain div with the expected.
+    const probe = document.createElement('div');
+    probe.style.background = LIGHT_SURFACE.background;
+    expect(el.style.background).toBe(probe.style.background);
+  });
+
+  it('dark surface overlays the theme background', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('hi'))] })]);
+    const { container } = render(
+      <LinearDocView doc={doc} theme={DEFAULT_THEME} surface={DARK_SURFACE} />,
+    );
+    const el = container.querySelector('.squisq-linear') as HTMLElement;
+    const probe = document.createElement('div');
+    probe.style.background = DARK_SURFACE.background;
+    expect(el.style.background).toBe(probe.style.background);
+  });
 });

package/src/hooks/useAutoSurface.ts

@@ -0,0 +1,33 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { DARK_SURFACE, LIGHT_SURFACE, type SurfaceScheme } from '@bendyline/squisq/schemas';
+
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+const getServerSnapshot = () => LIGHT_SURFACE;
+
+/**
+ * Live-track `prefers-color-scheme` and return a stable SurfaceScheme.
+ * `enabled: false` short-circuits to LIGHT_SURFACE (callers pass `false`
+ * when a static surface was provided so the hook never observes the
+ * media query). The `MediaQueryList` and the `subscribe`/`getSnapshot`
+ * callbacks are memoized so `useSyncExternalStore` doesn't resubscribe on
+ * every parent render.
+ */
+export function useAutoSurface(enabled: boolean): SurfaceScheme {
+  const mql = useMemo(
+    () => (enabled && typeof window !== 'undefined' ? window.matchMedia(DARK_QUERY) : null),
+    [enabled],
+  );
+
+  const subscribe = useCallback(
+    (cb: () => void) => {
+      if (!mql) return () => {};
+      mql.addEventListener('change', cb);
+      return () => mql.removeEventListener('change', cb);
+    },
+    [mql],
+  );
+
+  const getSnapshot = useCallback(() => (mql?.matches ? DARK_SURFACE : LIGHT_SURFACE), [mql]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/index.ts

@@ -11,6 +11,7 @@ export { DocPlayerWithSidebar } from './DocPlayerWithSidebar.js';
 export { DocProgressBar } from './DocProgressBar.js';
 export { MarkdownRenderer } from './MarkdownRenderer.js';
 export { LinearDocView } from './LinearDocView.js';
+export type { LinearDocViewProps, ImageDisplayMode } from './LinearDocView.js';
 
 // Layer components
 export { ImageLayer } from './layers/ImageLayer.js';