@open-slide/core 1.5.0 → 1.7.0

package/src/app/components/inspector/inspector-provider.tsx

@@ -15,6 +15,7 @@ import { Button } from '@/components/ui/button';
 import { type SlideComment, useComments } from '@/lib/inspector/use-comments';
 import { type Edit, type EditOp, type EditResult, useEditor } from '@/lib/inspector/use-editor';
 import { useLocale } from '@/lib/use-locale';
+import { AssetPickerDialog } from './asset-picker-dialog';
 import { ImageCropDialog, type ImageCropRect } from './image-crop-dialog';
 
 export type SelectedTarget = {
@@ -263,6 +264,7 @@ type InspectorCtx = {
   cancelEdits: () => void;
   committing: boolean;
   openCrop: (anchor: HTMLImageElement) => void;
+  openReplace: (anchor: HTMLElement) => void;
 };
 
 const Ctx = createContext<InspectorCtx | null>(null);
@@ -273,7 +275,15 @@ export function useInspector(): InspectorCtx {
   return v;
 }
 
-export function InspectorProvider({ slideId, children }: { slideId: string; children: ReactNode }) {
+export function InspectorProvider({
+  slideId,
+  pageIndex,
+  children,
+}: {
+  slideId: string;
+  pageIndex: number;
+  children: ReactNode;
+}) {
   const [active, setActive] = useState(false);
   const [selected, setSelected] = useState<SelectedTarget | null>(null);
   const { comments, error, refetch, add, remove } = useComments(slideId);
@@ -296,6 +306,11 @@ export function InspectorProvider({ slideId, children }: { slideId: string; chil
     initialPosition: { x: number; y: number };
     initialRect: ImageCropRect | null;
   } | null>(null);
+  const [replaceTarget, setReplaceTarget] = useState<{
+    line: number;
+    column: number;
+    anchor: HTMLElement;
+  } | null>(null);
   const t = useLocale();
 
   const ensureInstanceId = useCallback((el: HTMLElement): string => {
@@ -871,6 +886,35 @@ export function InspectorProvider({ slideId, children }: { slideId: string; chil
     return () => observer?.disconnect();
   }, []);
 
+  useEffect(() => {
+    void pageIndex;
+    setSelected(null);
+  }, [pageIndex]);
+
+  // Never clear `selected` on a miss: the observer can fire between an
+  // "old removed" and "new added" mutation batch, and clearing then would
+  // drop a selection that's about to reattach on the next fire.
+  useEffect(() => {
+    if (!selected) return;
+    const root = document.querySelector<HTMLElement>('[data-inspector-root]');
+    if (!root) return;
+
+    const revalidate = () => {
+      if (selected.anchor.isConnected) return;
+      const next = root.querySelector<HTMLElement>(
+        `[data-slide-loc="${selected.line}:${selected.column}"]`,
+      );
+      if (next && next !== selected.anchor) {
+        setSelected({ ...selected, anchor: next });
+      }
+    };
+
+    revalidate();
+    const observer = new MutationObserver(revalidate);
+    observer.observe(root, { childList: true, subtree: true });
+    return () => observer.disconnect();
+  }, [selected]);
+
   const toggle = useCallback(() => {
     setActive((a) => {
       if (a) setSelected(null);
@@ -883,6 +927,27 @@ export function InspectorProvider({ slideId, children }: { slideId: string; chil
     setSelected(null);
   }, []);
 
+  const openReplace = useCallback((anchor: HTMLElement) => {
+    const loc = anchor.dataset.slideLoc;
+    if (!loc) return;
+    const [lineStr, columnStr] = loc.split(':');
+    const line = Number(lineStr);
+    const column = Number(columnStr);
+    if (!Number.isFinite(line) || !Number.isFinite(column)) return;
+    setReplaceTarget({ line, column, anchor });
+  }, []);
+
+  useEffect(() => {
+    if (import.meta.env.PROD) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.target instanceof HTMLElement && e.target.matches('input, textarea')) return;
+      if (e.key !== 'i' && e.key !== 'I') return;
+      toggle();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [toggle]);
+
   const openCrop = useCallback((anchor: HTMLImageElement) => {
     const loc = anchor.dataset.slideLoc;
     if (!loc) return;
@@ -925,6 +990,7 @@ export function InspectorProvider({ slideId, children }: { slideId: string; chil
       cancelEdits,
       committing,
       openCrop,
+      openReplace,
     }),
     [
       slideId,
@@ -945,12 +1011,44 @@ export function InspectorProvider({ slideId, children }: { slideId: string; chil
       cancelEdits,
       committing,
       openCrop,
+      openReplace,
     ],
   );
 
   return (
     <Ctx.Provider value={value}>
       {children}
+      {replaceTarget && (
+        <AssetPickerDialog
+          slideId={slideId}
+          onClose={() => setReplaceTarget(null)}
+          onPick={(asset, scope) => {
+            const { line, column, anchor } = replaceTarget;
+            const assetPath =
+              scope === 'global' ? `@assets/${asset.name}` : `./assets/${asset.name}`;
+            const ops: EditOp[] = [
+              {
+                kind: 'set-attr-asset',
+                attr: 'src',
+                assetPath,
+                previewUrl: asset.url,
+              },
+            ];
+            if (anchor.tagName === 'IMG' && anchor.isConnected) {
+              const cs = window.getComputedStyle(anchor);
+              if (cs.objectFit !== 'cover' && cs.objectFit !== 'contain') {
+                ops.push({ kind: 'set-style', key: 'objectFit', value: 'cover' });
+              }
+              const op = cs.objectPosition.trim();
+              if (!op || op === '0% 0%' || op === 'auto') {
+                ops.push({ kind: 'set-style', key: 'objectPosition', value: '50% 50%' });
+              }
+            }
+            bufferOps(line, column, anchor, ops);
+            setReplaceTarget(null);
+          }}
+        />
+      )}
       {cropTarget && (
         <ImageCropDialog
           src={cropTarget.src}
@@ -1064,6 +1162,9 @@ export function InspectToggleButton() {
     >
       <Crosshair className="size-3.5" />
       <span className="hidden md:inline">{t.inspector.inspect}</span>
+      <kbd className="ml-1 hidden rounded-[3px] bg-foreground/10 px-1 font-mono text-[9.5px] tracking-[0.04em] md:inline">
+        I
+      </kbd>
     </Button>
   );
 }

package/src/app/components/panel/save-card.tsx

@@ -91,15 +91,15 @@ export function SaveCard({
           </div>
         )}
         {justSaved ? (
-          <span className="flex items-center gap-1.5 px-2.5 text-[12px] font-medium text-foreground">
-            <Check className="size-3.5 text-[oklch(0.55_0.13_165)]" strokeWidth={2.5} />
+          <span className="flex items-center gap-1.5 whitespace-nowrap px-2.5 text-[12px] font-medium text-foreground">
+            <Check className="size-3.5 shrink-0 text-[oklch(0.55_0.13_165)]" strokeWidth={2.5} />
             {resolvedSavedLabel}
           </span>
         ) : dirty || committing ? (
-          <span className="inline-flex items-center gap-1.5 px-2.5 text-[12px] font-medium text-foreground">
+          <span className="inline-flex items-center gap-1.5 whitespace-nowrap px-2.5 text-[12px] font-medium text-foreground">
             <span
               aria-hidden
-              className="size-1.5 rounded-full bg-brand shadow-[0_0_0_3px_var(--brand-soft)]"
+              className="size-1.5 shrink-0 rounded-full bg-brand shadow-[0_0_0_3px_var(--brand-soft)]"
             />
             <span className="nums">{unsavedLabel}</span>
           </span>

package/src/app/components/player.tsx

@@ -3,6 +3,8 @@ import { useWheelPageNavigation } from '@/lib/use-wheel-page-navigation';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../lib/design';
 import type { Page } from '../lib/sdk';
+import type { SlideTransition } from '../lib/transition';
+import { usePrefersReducedMotion } from '../lib/use-prefers-reduced-motion';
 import { PresentBlackoutOverlay } from './present/blackout-overlay';
 import { PresentControlBar } from './present/control-bar';
 import { PresentHelpOverlay } from './present/help-overlay';
@@ -19,6 +21,7 @@ import {
 } from './present/use-presenter-channel';
 import { useTouchSwipe } from './present/use-touch-swipe';
 import { SlideCanvas } from './slide-canvas';
+import { SlideTransitionLayer } from './slide-transition-layer';
 
 const IDLE_HIDE_MS = 2000;
 const BAR_HOTZONE_PX = 160;
@@ -26,6 +29,7 @@ const BAR_HOTZONE_PX = 160;
 type Props = {
   pages: Page[];
   design?: DesignSystem;
+  transition?: SlideTransition;
   index: number;
   onIndexChange: (index: number) => void;
   onExit: () => void;
@@ -43,6 +47,7 @@ type Props = {
 export function Player({
   pages,
   design,
+  transition,
   index,
   onIndexChange,
   onExit,
@@ -51,6 +56,7 @@ export function Player({
   slideId,
   fullscreen = true,
 }: Props) {
+  const prefersReducedMotion = usePrefersReducedMotion();
   const rootRef = useRef<HTMLDivElement | null>(null);
   // Mirrored as state so descendants portaling *into* the player subtree
   // (tooltips, popovers — the body is outside the fullscreen tree) re-render
@@ -283,8 +289,6 @@ export function Player({
   const hideCursor =
     controls && (laser || keyboardDriven || (idle && !overlayActive && !pointerNearBottom));
 
-  const PageComp = pages[index];
-
   return (
     <div
       ref={setRoot}
@@ -295,7 +299,13 @@ export function Player({
       )}
     >
       <SlideCanvas flat design={design}>
-        {PageComp ? <PageComp /> : null}
+        <SlideTransitionLayer
+          pages={pages}
+          index={index}
+          total={pages.length}
+          moduleTransition={transition}
+          disabled={prefersReducedMotion}
+        />
       </SlideCanvas>
 
       <button

package/src/app/components/present/overview-grid.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../../lib/design';
+import { SlidePageProvider } from '../../lib/page-context';
 import type { Page } from '../../lib/sdk';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../../lib/sdk';
 import { SlideCanvas } from '../slide-canvas';
@@ -136,7 +137,9 @@ export function PresentOverviewGrid({ pages, design, open, current, onClose, onS
                     freezeMotion
                     design={design}
                   >
-                    <PageComp />
+                    <SlidePageProvider index={i} total={pages.length}>
+                      <PageComp />
+                    </SlidePageProvider>
                   </SlideCanvas>
                   {isCurrent && (
                     <span

package/src/app/components/slide-transition-layer.tsx

@@ -0,0 +1,154 @@
+import { useEffect, useRef, useState } from 'react';
+import { SlidePageProvider } from '../lib/page-context';
+import type { Page } from '../lib/sdk';
+import { resolveTransition, type SlideTransition, type TransitionPhase } from '../lib/transition';
+
+type Props = {
+  pages: Page[];
+  index: number;
+  total: number;
+  moduleTransition?: SlideTransition;
+  disabled?: boolean;
+};
+
+type Direction = 'forward' | 'backward';
+
+const DEFAULT_EASING = 'cubic-bezier(.4, 0, .2, 1)';
+
+function runPhase(
+  el: HTMLElement,
+  phase: TransitionPhase | undefined,
+  fallbackDuration: number,
+  fallbackEasing: string,
+): Animation | null {
+  if (!phase) return null;
+  return el.animate(phase.keyframes, {
+    duration: phase.duration ?? fallbackDuration,
+    easing: phase.easing ?? fallbackEasing,
+    delay: phase.delay ?? 0,
+    fill: 'both',
+  });
+}
+
+export function SlideTransitionLayer({ pages, index, total, moduleTransition, disabled }: Props) {
+  const [current, setCurrent] = useState(index);
+  const [outgoing, setOutgoing] = useState<number | null>(null);
+  const [direction, setDirection] = useState<Direction>('forward');
+
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+  const outgoingLayerRef = useRef<HTMLDivElement | null>(null);
+  const incomingLayerRef = useRef<HTMLDivElement | null>(null);
+  const animsRef = useRef<Animation[]>([]);
+  const currentRef = useRef(current);
+  currentRef.current = current;
+
+  useEffect(() => {
+    if (index === currentRef.current) return;
+
+    const prev = currentRef.current;
+    const next = index;
+
+    // Interrupt: cancel in-flight animations. The previously-incoming page
+    // (currentRef) becomes the new outgoing; React reuses its DOM slot.
+    for (const a of animsRef.current) {
+      try {
+        a.cancel();
+      } catch {}
+    }
+    animsRef.current = [];
+
+    const transition = resolveTransition(pages, next, moduleTransition);
+    if (disabled || !transition) {
+      setCurrent(next);
+      setOutgoing(null);
+      return;
+    }
+
+    setDirection(next > prev ? 'forward' : 'backward');
+    setOutgoing(prev);
+    setCurrent(next);
+  }, [index, pages, moduleTransition, disabled]);
+
+  useEffect(() => {
+    if (outgoing === null) return;
+
+    const transition = resolveTransition(pages, current, moduleTransition);
+    const wrapper = wrapperRef.current;
+    const out = outgoingLayerRef.current;
+    const inc = incomingLayerRef.current;
+    if (!transition || !wrapper || !out || !inc) {
+      setOutgoing(null);
+      return;
+    }
+
+    wrapper.dataset.osdDir = direction;
+    wrapper.style.setProperty('--osd-dir', direction === 'forward' ? '1' : '-1');
+
+    const easing = transition.easing ?? DEFAULT_EASING;
+    const duration = transition.duration;
+
+    const anims: Animation[] = [];
+    const exitAnim = runPhase(out, transition.exit, duration, easing);
+    const enterAnim = runPhase(inc, transition.enter, duration, easing);
+    if (exitAnim) anims.push(exitAnim);
+    if (enterAnim) anims.push(enterAnim);
+    animsRef.current = anims;
+
+    if (anims.length === 0) {
+      setOutgoing(null);
+      return;
+    }
+
+    let cancelled = false;
+    Promise.all(anims.map((a) => a.finished))
+      .then(() => {
+        if (cancelled) return;
+        animsRef.current = [];
+        setOutgoing(null);
+      })
+      .catch(() => {
+        // AbortError fires when we cancel mid-flight on an interrupt.
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [outgoing, current, direction, pages, moduleTransition]);
+
+  useEffect(() => {
+    return () => {
+      for (const a of animsRef.current) {
+        try {
+          a.cancel();
+        } catch {}
+      }
+      animsRef.current = [];
+    };
+  }, []);
+
+  const CurrentPage = pages[current];
+  const OutgoingPage = outgoing !== null ? pages[outgoing] : null;
+
+  return (
+    <div
+      ref={wrapperRef}
+      className="relative h-full w-full"
+      style={{ background: 'var(--osd-bg)' }}
+    >
+      {OutgoingPage && outgoing !== null ? (
+        <div ref={outgoingLayerRef} className="absolute inset-0">
+          <SlidePageProvider index={outgoing} total={total}>
+            <OutgoingPage />
+          </SlidePageProvider>
+        </div>
+      ) : null}
+      {CurrentPage ? (
+        <div ref={incomingLayerRef} className="absolute inset-0">
+          <SlidePageProvider index={current} total={total}>
+            <CurrentPage />
+          </SlidePageProvider>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/app/components/style-panel/style-panel.tsx

@@ -211,6 +211,9 @@ export function DesignToggleButton({
     >
       <Palette className="size-3.5" />
       <span className="hidden md:inline">{t.stylePanel.designToggle}</span>
+      <kbd className="ml-1 hidden rounded-[3px] bg-foreground/10 px-1 font-mono text-[9.5px] tracking-[0.04em] md:inline">
+        D
+      </kbd>
     </Button>
   );
 }

package/src/app/components/themes/theme-detail.tsx

@@ -4,6 +4,7 @@ import { Link } from 'react-router-dom';
 import { Button } from '@/components/ui/button';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
+import { SlidePageProvider } from '../../lib/page-context';
 import type { SlideModule } from '../../lib/sdk';
 import { loadSlide, slidesByTheme } from '../../lib/slides';
 import { loadThemeDemo, type ThemeDemoModule, themes } from '../../lib/themes';
@@ -106,7 +107,9 @@ export function ThemeDetail({ themeId, onBack }: { themeId: string; onBack: () =
                 </div>
               ) : Current ? (
                 <SlideCanvas flat freezeMotion design={demo.design}>
-                  <Current />
+                  <SlidePageProvider index={pageIndex} total={totalPages}>
+                    <Current />
+                  </SlidePageProvider>
                 </SlideCanvas>
               ) : null}
             </div>
@@ -227,7 +230,9 @@ function ThemeSlideCard({ id }: { id: string }) {
         {FirstPage ? (
           <div className="h-full w-full motion-safe:transition-transform motion-safe:duration-300 motion-safe:group-hover:scale-[1.03]">
             <SlideCanvas flat freezeMotion design={slide?.design}>
-              <FirstPage />
+              <SlidePageProvider index={0} total={slide?.default.length ?? 1}>
+                <FirstPage />
+              </SlidePageProvider>
             </SlideCanvas>
           </div>
         ) : (

package/src/app/components/themes/themes-gallery.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 import { format, useLocale } from '@/lib/use-locale';
+import { SlidePageProvider } from '../../lib/page-context';
 import { loadThemeDemo, type Theme, type ThemeDemoModule, themes } from '../../lib/themes';
 import { SlideCanvas } from '../slide-canvas';
 
@@ -78,7 +79,9 @@ function ThemePreview({ theme }: { theme: Theme }) {
   return (
     <div className="h-full w-full motion-safe:transition-transform motion-safe:duration-300 motion-safe:group-hover:scale-[1.03]">
       <SlideCanvas flat freezeMotion design={demo.design}>
-        <FirstPage />
+        <SlidePageProvider index={0} total={demo.default.length}>
+          <FirstPage />
+        </SlidePageProvider>
       </SlideCanvas>
     </div>
   );

package/src/app/components/thumbnail-rail.tsx

@@ -28,6 +28,7 @@ import { ScrollArea } from '@/components/ui/scroll-area';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../lib/design';
+import { SlidePageProvider } from '../lib/page-context';
 import type { Page } from '../lib/sdk';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../lib/sdk';
 import { SlideCanvas } from './slide-canvas';
@@ -118,7 +119,9 @@ export function ThumbnailRail({
                     style={{ width, height: HORIZONTAL_THUMB_HEIGHT }}
                   >
                     <SlideCanvas scale={scale} center={false} flat freezeMotion design={design}>
-                      <PageComp />
+                      <SlidePageProvider index={i} total={pages.length}>
+                        <PageComp />
+                      </SlidePageProvider>
                     </SlideCanvas>
                   </div>
                 </button>
@@ -155,6 +158,7 @@ export function ThumbnailRail({
     const inner = (
       <ThumbContents
         index={i}
+        total={pages.length}
         active={active}
         page={PageComp}
         design={design}
@@ -236,6 +240,7 @@ function thumbButtonClass(active: boolean): string {
 
 function ThumbContents({
   index,
+  total,
   active,
   page: PageComp,
   design,
@@ -244,6 +249,7 @@ function ThumbContents({
   height,
 }: {
   index: number;
+  total: number;
   active: boolean;
   page: Page;
   design?: DesignSystem;
@@ -271,7 +277,9 @@ function ThumbContents({
         style={{ width: thumbWidth, height }}
       >
         <SlideCanvas scale={scale} center={false} flat freezeMotion design={design}>
-          <PageComp />
+          <SlidePageProvider index={index} total={total}>
+            <PageComp />
+          </SlidePageProvider>
         </SlideCanvas>
         {active && (
           <span

package/src/app/lib/assets.ts

@@ -6,6 +6,7 @@ export type AssetEntry = {
   mtime: number;
   mime: string;
   url: string;
+  unused: boolean;
 };
 
 export type UploadOptions = { overwrite?: boolean };
@@ -90,6 +91,7 @@ export async function uploadWithAutoRename(
     mtime: body?.mtime ?? Date.now(),
     mime: body?.mime ?? uploaded.type ?? 'application/octet-stream',
     url: body?.url ?? `/__assets/${slideId}/${encodeURIComponent(uploaded.name)}`,
+    unused: body?.unused ?? false,
   };
   return { ok: true, status: res.status, entry };
 }

package/src/app/lib/export-html.ts

@@ -1,6 +1,7 @@
 import { createElement } from 'react';
 import { createRoot } from 'react-dom/client';
 import { designToCssVars } from './design';
+import { SlidePageProvider } from './page-context';
 import type { SlideModule } from './sdk';
 
 type AssetEntry = { name: string; bytes: Uint8Array };
@@ -82,13 +83,17 @@ async function renderPagesToHtml(pages: NonNullable<SlideModule['default']>): Pr
 
   const result: string[] = [];
   try {
-    for (const Page of pages) {
+    for (let i = 0; i < pages.length; i++) {
+      const Page = pages[i];
+      if (!Page) continue;
       const host = document.createElement('div');
       host.style.width = '1920px';
       host.style.height = '1080px';
       container.appendChild(host);
       const root = createRoot(host);
-      root.render(createElement(Page));
+      root.render(
+        createElement(SlidePageProvider, { index: i, total: pages.length }, createElement(Page)),
+      );
       await nextPaint();
       await nextPaint();
       result.push(host.innerHTML);

package/src/app/lib/export-pdf.ts

@@ -1,6 +1,7 @@
 import { createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { designToCssVars } from './design';
+import { SlidePageProvider } from './page-context';
 import { isFrameAnimationSettled, waitForDataWaitfor, waitForFonts } from './print-ready';
 import type { SlideModule } from './sdk';
 
@@ -62,6 +63,20 @@ const PRINT_STYLES = `
     transform: scale(0.5);
     transform-origin: top left;
   }
+  /* Chromium serializes box-shadow and CSS gradients as PDF transparency
+     groups / soft masks. macOS Preview re-composites those on every page
+     turn, causing 0.5–2s per-page lag. Strip them in the print container
+     only — gradients on pseudo-elements via CSS (DOM walk can't reach them),
+     inline-style gradients via neutralizeGradientBackgrounds() below. */
+  #${PRINT_ROOT_ID} *,
+  #${PRINT_ROOT_ID} *::before,
+  #${PRINT_ROOT_ID} *::after {
+    box-shadow: none !important;
+  }
+  #${PRINT_ROOT_ID} *::before,
+  #${PRINT_ROOT_ID} *::after {
+    background-image: none !important;
+  }
 }
 `;
 
@@ -109,7 +124,9 @@ export async function exportSlideAsPdf(
 
   const reactRoots: Root[] = [];
   const frames: HTMLElement[] = [];
-  for (const Page of pages) {
+  for (let i = 0; i < pages.length; i++) {
+    const Page = pages[i];
+    if (!Page) continue;
     const host = document.createElement('div');
     host.className = 'os-print-frame';
     host.setAttribute('data-osd-canvas', '');
@@ -126,7 +143,9 @@ export async function exportSlideAsPdf(
     root.appendChild(host);
     frames.push(host);
     const r = createRoot(inner);
-    r.render(createElement(Page));
+    r.render(
+      createElement(SlidePageProvider, { index: i, total: pages.length }, createElement(Page)),
+    );
     reactRoots.push(r);
   }
   // Yield once so React commits all pages and CSS animations actually start
@@ -155,6 +174,7 @@ export async function exportSlideAsPdf(
     }
 
     await waitForDataWaitfor(root);
+    neutralizeGradientBackgrounds(root);
     await sleep(100); // flush layout
 
     onProgress?.({ phase: 'printing', current: total, total, percent: 99 });
@@ -170,6 +190,18 @@ export async function exportSlideAsPdf(
   }
 }
 
+// Strip inline-style gradients from background-image so Chromium does not
+// emit them as PDF soft masks. url(...) backgrounds are preserved.
+function neutralizeGradientBackgrounds(root: HTMLElement): void {
+  const elements = root.querySelectorAll<HTMLElement>('*');
+  for (const el of elements) {
+    const bg = getComputedStyle(el).backgroundImage;
+    if (bg?.includes('gradient(')) {
+      el.style.backgroundImage = 'none';
+    }
+  }
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }