@bendyline/squisq-react 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-react",
-  "version": "1.1.1",
+  "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.1"
+    "@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,20 +333,37 @@ 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
+      // leave coverGraceActive stuck at true because the effect body won't
+      // re-run (coverWasShowing.current is now false).
       coverGraceTimer.current = setTimeout(() => setCoverGraceActive(false), 3000);
-      return () => clearTimeout(coverGraceTimer.current);
     }
   }, [isPlaying, coverBlock, renderMode]);
 
+  // Always clear the grace timer on unmount
+  useEffect(() => () => clearTimeout(coverGraceTimer.current), []);
+
   // Determine if we should show the cover block
   // Show cover when: has cover block, not playing, at time 0, not in render mode
   // OR during the grace period after first play, OR when coverForced (render mode)
@@ -338,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
@@ -779,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>
     );
   }
@@ -851,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 ────────────────────────────────────────────────────────
 
 /**
@@ -257,8 +285,10 @@ function getTemplateDefaults(
       return { fact: headingText, explanation: bodyText || headingText };
     case 'comparisonBar':
       return { leftLabel: 'A', leftValue: 60, rightLabel: 'B', rightValue: 40 };
-    case 'listBlock':
-      return { items: extractListItems(contents) || ['Item 1', 'Item 2', 'Item 3'] };
+    case 'listBlock': {
+      const items = extractListItems(contents);
+      return { items: items.length > 0 ? items : ['Item 1', 'Item 2', 'Item 3'] };
+    }
     case 'definitionCard':
       return { term: headingText, definition: bodyText || headingText };
     case 'dateEvent':
@@ -292,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;
@@ -319,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,
@@ -406,6 +450,20 @@ export function LinearDocView({
             border-top: 1px solid var(--squisq-linear-muted);
             margin: 1.5em 0;
           }
+          .squisq-linear-content img {
+            max-width: 100%;
+            height: auto;
+            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

@@ -22,6 +22,7 @@ import type {
   MarkdownTableRow,
   MarkdownTableCell,
 } from '@bendyline/squisq/markdown';
+import { useMediaUrl } from './hooks/MediaContext';
 
 // ── Props ──────────────────────────────────────────────────────────
 
@@ -39,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 (
@@ -86,13 +104,7 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
 
       case 'image':
         return (
-          <img
-            key={key}
-            className="squisq-md-image"
-            src={node.url}
-            alt={node.alt ?? ''}
-            title={node.title ?? undefined}
-          />
+          <MdImage key={key} src={node.url} alt={node.alt ?? ''} title={node.title ?? undefined} />
         );
 
       case 'break':
@@ -143,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;
     }
@@ -343,6 +369,14 @@ function renderBlocks(nodes: MarkdownBlockNode[], keyPrefix = ''): React.ReactNo
   return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`));
 }
 
+// ── Image with MediaProvider resolution ───────────────────────────
+
+/** Renders an <img> that resolves its src through the MediaProvider when available. */
+function MdImage({ src, alt, title }: { src: string; alt: string; title?: string }) {
+  const resolved = useMediaUrl(src, '.');
+  return <img className="squisq-md-image" src={resolved} alt={alt} title={title} />;
+}
+
 // ── Main Component ─────────────────────────────────────────────────
 
 /**

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';

package/src/layers/ImageLayer.tsx

@@ -61,8 +61,8 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
         <foreignObject x={finalX} y={finalY} width={width} height={height}>
           <div
             style={{
-              width: '100%',
-              height: '100%',
+              width: `${width}px`,
+              height: `${height}px`,
               overflow: 'hidden',
             }}
           >
@@ -71,8 +71,8 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
               alt={content.alt || ''}
               className={kbStyle.className}
               style={{
-                width: '100%',
-                height: '100%',
+                width: `${width}px`,
+                height: `${height}px`,
                 objectFit: 'cover',
                 objectPosition: 'center',
                 display: 'block',
@@ -101,8 +101,8 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
             src={src}
             alt={content.alt || ''}
             style={{
-              width: '100%',
-              height: '100%',
+              width: `${width}px`,
+              height: `${height}px`,
               objectFit: 'cover',
               objectPosition: 'center',
               display: 'block',

package/src/layers/ShapeLayer.tsx

@@ -49,8 +49,8 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
         <foreignObject x={x} y={y} width={width} height={height}>
           <div
             style={{
-              width: '100%',
-              height: '100%',
+              width: `${width}px`,
+              height: `${height}px`,
               background: fill,
               borderRadius: content.borderRadius ? `${content.borderRadius}px` : undefined,
               pointerEvents: 'none',

package/src/layers/TableLayer.tsx

@@ -51,8 +51,8 @@ export function TableLayer({ layer, viewport, blockTime }: TableLayerProps) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         {...({ xmlns: 'http://www.w3.org/1999/xhtml' } as any)}
         style={{
-          width: '100%',
-          height: '100%',
+          width: `${width}px`,
+          height: `${height}px`,
           display: 'flex',
           alignItems: 'center',
           justifyContent: 'center',

package/src/layers/VideoLayer.tsx

@@ -134,8 +134,8 @@ export function VideoLayer({
           data-clip-start={content.clipStart}
           data-clip-end={content.clipEnd}
           style={{
-            width: '100%',
-            height: '100%',
+            width: `${width}px`,
+            height: `${height}px`,
             objectFit: content.fit || 'cover',
             objectPosition: 'center',
             display: 'block',

package/src/standalone-entry.tsx

@@ -86,10 +86,22 @@ function createInlineMediaProvider(
   images: Record<string, string>,
   basePath: string,
 ): MediaProvider {
+  // Doc image references may not exactly match image map keys
+  // (e.g., "images/hero.jpg" vs "hero.jpg"). Build a filename-keyed
+  // lookup so resolution can fall back to basename matching.
+  const byFilename: Record<string, string> = {};
+  for (const key of Object.keys(images)) {
+    const filename = key.split('/').pop()!;
+    byFilename[filename] = images[key];
+  }
+
   return {
     async resolveUrl(relativePath: string): Promise<string> {
       if (relativePath in images) return images[relativePath];
-      // Fallback to basePath
+      const stripped = relativePath.replace(/^\.\//, '');
+      if (stripped !== relativePath && stripped in images) return images[stripped];
+      const filename = relativePath.split('/').pop()!;
+      if (filename in byFilename) return byFilename[filename];
       if (
         relativePath.startsWith('http') ||
         relativePath.startsWith('data:') ||