@devbycrux/editor 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devbycrux/editor",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "exports": {

package/src/carousel/CarouselEditor.tsx

@@ -151,7 +151,7 @@ function isTypingTarget(t: EventTarget | null): boolean {
 
 // ── CarouselEditor ────────────────────────────────────────────────────────────
 
-export default function CarouselEditor<P extends Project = Project>({ project: initialProject, adapter, onProjectChange, theme, slots }: Props<P>) {
+export default function CarouselEditor<P extends Project = Project>({ project: initialProject, adapter, onProjectChange, theme, slots, hiddenElementIds, onToggleElementVisibility, onSelectionChange }: Props<P>) {
   const state = useProjectState(adapter, initialProject.id, initialProject)
   const project = state.project
   const slides = project.slides ?? []
@@ -339,6 +339,12 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
   const selectedSlide = slides.find(s => s.id === selectedSlideId)
   const selectedElement = selectedSlide?.elements.find(el => el.id === selectedElementId)
 
+  // Notify the host of selection changes so it can drive selection-aware chrome
+  // (e.g. a regen action in a toolbar slot). Fires with the element or null.
+  useEffect(() => {
+    onSelectionChange?.(selectedElement ?? null)
+  }, [selectedElement, onSelectionChange])
+
   const [w, h] = project.settings.resolution
   const canvasContainerRef = useRef<HTMLDivElement>(null)
   const [canvasContainerSize, setCanvasContainerSize] = useState<{ w: number; h: number }>({ w: 600, h: 700 })
@@ -387,21 +393,24 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
           <span className="text-xs font-medium">Refresh</span>
         </button>
 
-        <button
-          onClick={handleRender}
-          disabled={rendering || project.status === 'pending' || slides.length === 0}
-          className="absolute top-3 right-3 z-30 flex items-center gap-2 px-3 py-2 rounded-md border border-blue-500/50 bg-blue-600/80 text-white hover:bg-blue-600 hover:border-blue-400 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-          title={
-            project.status === 'pending'
-              ? 'Wait for the agent to finish before rendering'
-              : slides.length === 0
-              ? 'Add slides before rendering'
-              : 'Render all slides as PNGs'
-          }
-        >
-          <Download size={18} />
-          <span className="text-xs font-medium">{rendering ? 'Starting…' : 'Render'}</span>
-        </button>
+        <div className="absolute top-3 right-3 z-30 flex items-center gap-2">
+          {slots?.toolbarActions}
+          <button
+            onClick={handleRender}
+            disabled={rendering || project.status === 'pending' || slides.length === 0}
+            className="flex items-center gap-2 px-3 py-2 rounded-md border border-blue-500/50 bg-blue-600/80 text-white hover:bg-blue-600 hover:border-blue-400 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
+            title={
+              project.status === 'pending'
+                ? 'Wait for the agent to finish before rendering'
+                : slides.length === 0
+                ? 'Add slides before rendering'
+                : 'Render all slides as PNGs'
+            }
+          >
+            <Download size={18} />
+            <span className="text-xs font-medium">{rendering ? 'Starting…' : 'Render'}</span>
+          </button>
+        </div>
 
         {project.status === 'pending' ? (
           <div className="flex flex-col items-center gap-6 text-center max-w-lg w-full">
@@ -461,6 +470,7 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
                 updateImageCrop={state.updateImageCrop}
                 cropElementId={cropElementId}
                 onExitCrop={() => setCropElementId(null)}
+                hiddenElementIds={hiddenElementIds}
               />
             </div>
             <p className="flex-shrink-0 text-xs text-gray-500 text-center max-w-md">
@@ -505,6 +515,8 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
           onReorderElement={handleReorderElement}
           onEnterCrop={(_slideId, elementId) => { setSelectedElementId(elementId); setCropElementId(elementId) }}
           updateOverlayProp={state.updateOverlayProp}
+          hiddenElementIds={hiddenElementIds}
+          onToggleElementVisibility={onToggleElementVisibility}
         />
         {slots?.assetsPanel && (
           <div className="border-t border-gray-800 flex flex-col overflow-hidden" style={{ minHeight: 180 }}>

package/src/carousel/ReadOnlySlide.tsx

@@ -0,0 +1,90 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+import type { Slide, Project, EditorAdapter } from '../types'
+import SlideCanvas from './SlideCanvas'
+
+/**
+ * Public read-only props for rendering a single carousel slide. This is the
+ * clean read-only surface over the internal (interactive-heavy) SlideCanvas
+ * Props: it exposes only the fields a non-editing consumer needs — geometry,
+ * an optional explicit scale or auto-fit, and the adapter capabilities the
+ * render path can use (image resolution, overlay compilation, file watching).
+ */
+export interface ReadOnlySlideProps {
+  slide: Slide
+  /** Native slide width (resolution[0]). */
+  width: number
+  /** Native slide height (resolution[1]). */
+  height: number
+  /** Explicit scale; if omitted and autoFit is on, the scale is measured. */
+  scale?: number
+  /**
+   * When true, measure the wrapper's box via a ResizeObserver and fit the slide
+   * with `min(parentW/width, parentH/height)`. When false (default), the
+   * effective scale is `scale ?? 1`.
+   */
+  autoFit?: boolean
+  resolveImageSrc?: EditorAdapter<Project>['resolveImageSrc']
+  compileOverlay?: EditorAdapter<Project>['compileOverlay']
+  watchFile?: EditorAdapter<Project>['watchFile']
+  /** Element ids to omit from the render (non-persisted). */
+  hiddenElementIds?: string[]
+}
+
+/**
+ * Thin read-only renderer for a single carousel slide. Renders a
+ * non-interactive SlideCanvas — no selection, drag, resize, rotate, crop, or
+ * text-edit chrome. The wrapper fills its sized parent (width/height: 100%) so
+ * the parent's `aspect-ratio` controls layout; with `autoFit` the slide is
+ * scaled to fit that box.
+ */
+export default function ReadOnlySlide({
+  slide,
+  width,
+  height,
+  scale: explicitScale,
+  autoFit = false,
+  resolveImageSrc,
+  compileOverlay,
+  watchFile,
+  hiddenElementIds,
+}: ReadOnlySlideProps) {
+  // Auto-fit: measure the wrapper and pick the largest scale that preserves the
+  // slide's aspect ratio. Consumers just give the wrapper a sized parent (e.g. a
+  // box with `aspect-ratio: <w>/<h>; width: 100%`); no explicit scale needed.
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const [measuredScale, setMeasuredScale] = useState<number>(0)
+  useLayoutEffect(() => {
+    if (!autoFit || explicitScale !== undefined) return
+    const node = rootRef.current
+    if (!node) return
+    const compute = () => {
+      const w = node.clientWidth
+      const h = node.clientHeight
+      if (w === 0 || h === 0) return
+      const fit = Math.min(w / width, h / height)
+      if (Number.isFinite(fit) && fit > 0) setMeasuredScale(fit)
+    }
+    compute()
+    const ro = new ResizeObserver(compute)
+    ro.observe(node)
+    return () => ro.disconnect()
+  }, [autoFit, explicitScale, width, height])
+
+  const scale = explicitScale ?? (autoFit ? measuredScale : 1)
+
+  return (
+    <div ref={rootRef} style={{ width: '100%', height: '100%' }}>
+      <SlideCanvas
+        slide={slide}
+        width={width}
+        height={height}
+        interactive={false}
+        scale={scale}
+        resolveImageSrc={resolveImageSrc}
+        compileOverlay={compileOverlay}
+        watchFile={watchFile}
+        hiddenElementIds={hiddenElementIds}
+      />
+    </div>
+  )
+}

package/src/carousel/SlideCanvas.tsx

@@ -12,6 +12,7 @@ import {
 import { OverlayPreview } from '../preview/OverlayPreview'
 import { CanvasCropOverlay } from '../crop/CanvasCropOverlay'
 import { InlineTextEditor } from '../text/InlineTextEditor'
+import { ensureGoogleFontsLoaded } from '../lib/google-fonts'
 
 // Neutral fallback used only when no host `resolveImageSrc` is injected. The
 // package must not synthesize a host-shaped URL (e.g. Montaj's `/api/files`):
@@ -55,6 +56,12 @@ function OverlayElementView({
 }) {
   const duration = (element.overlay.props.duration as number | undefined) ?? 60
   const mergedProps = { ...element.overlay.props, offsetX: 0, offsetY: 0, scale: 1 }
+  // Inject any Google Fonts the overlay declares so the carousel preview renders
+  // with the same glyphs/metrics as the renderer. Resilient: the helper only
+  // appends a <link>; a font-fetch failure never breaks the overlay render.
+  useEffect(() => {
+    ensureGoogleFontsLoaded(element.googleFonts)
+  }, [element.googleFonts])
   return (
     <OverlayPreview
       compileOverlay={compileOverlay ?? noopCompiler}
@@ -106,6 +113,13 @@ interface Props {
   // Crop mode is owned here but the entry trigger lives in the property panel.
   cropElementId?: string | null
   onExitCrop?: () => void
+
+  /**
+   * Editor-only element ids to omit from this canvas (non-persisted). Used by
+   * the host's visibility toggle to hide a scrim/background while positioning
+   * overlays beneath it. Absent → all elements render.
+   */
+  hiddenElementIds?: string[]
 }
 
 export default function SlideCanvas({
@@ -128,9 +142,11 @@ export default function SlideCanvas({
   updateImageCrop,
   cropElementId,
   onExitCrop,
+  hiddenElementIds,
 }: Props) {
   const sid = slideId ?? slide.id
   const resolveSrc = resolveImageSrc ?? ((el: ImageElement) => resolveAssetDefault(el.src))
+  const hiddenSet = hiddenElementIds && hiddenElementIds.length ? new Set(hiddenElementIds) : null
 
   // Refs to each element wrapper so gesture previews can mutate DOM directly.
   const wrapperRefs = useRef<Map<string, HTMLDivElement>>(new Map())
@@ -295,6 +311,7 @@ export default function SlideCanvas({
 
   return (
     <div
+      data-interactive={interactive ? 'true' : undefined}
       style={{
         width: displayW,
         height: displayH,
@@ -353,6 +370,8 @@ export default function SlideCanvas({
         )}
 
         {slide.elements.map((element) => {
+          // Editor-only visibility: omit hidden elements from this canvas.
+          if (hiddenSet?.has(element.id)) return null
           const isSelected = selectedElementId === element.id
           const inCrop = cropState?.elementId === element.id
           const isRotated = (element.rotation ?? 0) !== 0
@@ -386,12 +405,42 @@ export default function SlideCanvas({
 
           const innerContent =
             element.type === 'image' ? (
-              <img
-                src={resolveSrc(element)}
-                draggable={false}
-                style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}
-                alt=""
-              />
+              // While actively cropping this element, the CanvasCropOverlay draws
+              // the full source with a draggable window on top — so show the plain
+              // (uncropped) base beneath it. Otherwise honor the committed crop.
+              element.crop && !inCrop ? (
+                // Cropped display: render the crop sub-rect [cx,cx+cw]×[cy,cy+ch]
+                // (fractions of the source) scaled to cover the element box. This
+                // mirrors Montaj's renderer (render/templates/slide.jsx): an
+                // overflow-hidden wrapper + an oversized cover image positioned by
+                // the crop rect. `maxWidth/maxHeight: 'none'` defeats Tailwind
+                // preflight's `img { max-width: 100% }`, which would otherwise
+                // clamp the oversized image and collapse offset crops to a sliver.
+                <div style={{ width: '100%', height: '100%', overflow: 'hidden' }}>
+                  <img
+                    src={resolveSrc(element)}
+                    draggable={false}
+                    style={{
+                      display: 'block',
+                      width: `${100 / element.crop.w}%`,
+                      height: `${100 / element.crop.h}%`,
+                      maxWidth: 'none',
+                      maxHeight: 'none',
+                      marginLeft: `${(-element.crop.x * 100) / element.crop.w}%`,
+                      marginTop: `${(-element.crop.y * 100) / element.crop.h}%`,
+                      objectFit: 'cover',
+                    }}
+                    alt=""
+                  />
+                </div>
+              ) : (
+                <img
+                  src={resolveSrc(element)}
+                  draggable={false}
+                  style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}
+                  alt=""
+                />
+              )
             ) : (
               <OverlayErrorBoundary
                 label={element.overlay.template.split('/').pop() ?? element.overlay.template}

package/src/carousel/SlidePropertyPanel.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import { Crop } from 'lucide-react'
+import { Crop, Eye, EyeOff } from 'lucide-react'
 import type {
   Project,
   Slide,
@@ -34,6 +34,37 @@ interface Props {
   updateOverlayProp?: (slideId: string, elementId: string, key: string, value: string) => Promise<void>
   // Adapter supplies overlay-schema listing (global + profile-scoped).
   adapter: EditorAdapter<Project>
+  // Editor-only element visibility (host-owned, non-persisted). When
+  // `onToggleElementVisibility` is supplied, an eye toggle is shown for the
+  // selected element; `hiddenElementIds` reflects the current hidden set.
+  hiddenElementIds?: string[]
+  onToggleElementVisibility?: (elementId: string) => void
+}
+
+// Small eye toggle to hide/show the selected element in the editor preview only
+// (never persisted). Absent host callback → not rendered.
+function HideToggle({
+  elementId,
+  isHidden,
+  onToggle,
+}: {
+  elementId: string
+  isHidden: boolean
+  onToggle?: (elementId: string) => void
+}) {
+  if (!onToggle) return null
+  return (
+    <button
+      type="button"
+      onClick={e => { e.stopPropagation(); onToggle(elementId) }}
+      title={isHidden ? 'Show in editor' : 'Hide from editor'}
+      aria-label={isHidden ? 'Show in editor' : 'Hide from editor'}
+      aria-pressed={isHidden}
+      className="text-gray-500 hover:text-white px-1"
+    >
+      {isHidden ? <EyeOff className="h-3.5 w-3.5" /> : <Eye className="h-3.5 w-3.5" />}
+    </button>
+  )
 }
 
 function numInput(
@@ -146,6 +177,8 @@ export default function SlidePropertyPanel({
   onEnterCrop,
   updateOverlayProp,
   adapter,
+  hiddenElementIds,
+  onToggleElementVisibility,
 }: Props) {
   // Map of jsxPath → GlobalOverlay for overlay prop schemas
   const [overlaySchemas, setOverlaySchemas] = useState<Map<string, GlobalOverlay>>(new Map())
@@ -225,7 +258,12 @@ export default function SlidePropertyPanel({
             <span className="text-xs font-semibold text-gray-400 uppercase tracking-wider">
               {element.type === 'image' ? 'Image' : 'Overlay'}
             </span>
-            <div className="flex gap-1">
+            <div className="flex items-center gap-1">
+              <HideToggle
+                elementId={element.id}
+                isHidden={hiddenElementIds?.includes(element.id) ?? false}
+                onToggle={onToggleElementVisibility}
+              />
               <button
                 onClick={() => onReorderElement(slide.id, element.id, 'forward')}
                 className="text-xs text-gray-500 hover:text-white px-1"

package/src/carousel/__tests__/CarouselEditor.test.tsx

@@ -232,4 +232,56 @@ describe('CarouselEditor — editor-core integration', () => {
     expect(adapter.saveCalls.length).toBe(before)
     document.body.removeChild(input)
   })
+
+  // Visibility toggle: ids in `hiddenElementIds` are omitted from the interactive
+  // canvas (editor-only; the thumbnail and `saveProject` are untouched).
+  it('omits hidden elements from the interactive canvas', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({
+      slides: [
+        {
+          id: 'slide-0',
+          base_color: '#ffffff',
+          elements: [
+            { id: 'el-a', type: 'image', src: 'a.png', x: 0, y: 0, w: 100, h: 100, rotation: 0 },
+            { id: 'el-b', type: 'image', src: 'b.png', x: 10, y: 10, w: 100, h: 100, rotation: 0 },
+          ],
+        },
+      ],
+    })
+    const { container } = render(
+      <CarouselEditor project={initial} adapter={adapter} onProjectChange={vi.fn()} hiddenElementIds={['el-b']} />,
+    )
+    // Visible element renders in the interactive canvas; hidden one does not.
+    await waitFor(() => expect(container.querySelector('[data-interactive] [data-element-id="el-a"]')).not.toBeNull())
+    expect(container.querySelector('[data-interactive] [data-element-id="el-b"]')).toBeNull()
+  })
+
+  // onSelectionChange fires with the selected element, and with null on deselect.
+  it('fires onSelectionChange on select and deselect', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const onSelectionChange = vi.fn()
+    const { container } = render(
+      <CarouselEditor project={initial} adapter={adapter} onProjectChange={vi.fn()} onSelectionChange={onSelectionChange} />,
+    )
+
+    const lastSelection = () => {
+      const calls = onSelectionChange.mock.calls
+      return calls[calls.length - 1]?.[0]
+    }
+
+    const wrapper = await waitFor(() => findInteractiveWrapper('el-img'))
+    await act(async () => { fireEvent.click(wrapper) })
+    await waitFor(() => {
+      expect(lastSelection()?.id).toBe('el-img')
+    })
+
+    // Click the interactive canvas background to clear selection.
+    const root = container.querySelector('[data-interactive]') as HTMLElement
+    await act(async () => { fireEvent.click(root) })
+    await waitFor(() => {
+      expect(lastSelection()).toBeNull()
+    })
+  })
 })

package/src/carousel/__tests__/ReadOnlySlide.test.tsx

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, waitFor } from '@testing-library/react'
+import type { ImageElement, OverlayElement, Slide } from '../../types'
+import ReadOnlySlide from '../ReadOnlySlide'
+
+// ── ResizeObserver mock plumbing ──────────────────────────────────────────────
+// jsdom has no ResizeObserver. We capture the instances so autoFit tests can
+// drive a callback with a controlled parent size.
+let roInstances: Array<{ cb: ResizeObserverCallback; el: Element | null }> = []
+beforeEach(() => {
+  roInstances = []
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    cb: ResizeObserverCallback
+    el: Element | null = null
+    constructor(cb: ResizeObserverCallback) {
+      this.cb = cb
+      roInstances.push(this)
+    }
+    observe(el: Element) {
+      this.el = el
+    }
+    unobserve() {}
+    disconnect() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+const imgEl: ImageElement = {
+  id: 'el-img',
+  type: 'image',
+  src: 'a.png',
+  x: 100,
+  y: 100,
+  w: 200,
+  h: 200,
+  rotation: 0,
+}
+
+const overlayEl: OverlayElement = {
+  id: 'el-ov',
+  type: 'overlay',
+  overlay: { template: '/overlays/lp-text.jsx', props: { text: 'Hola' } },
+  frame: 0,
+  x: 50,
+  y: 800,
+  w: 400,
+  h: 120,
+  rotation: 0,
+}
+
+function makeSlide(elements: Slide['elements']): Slide {
+  return { id: 'slide-0', base_color: '#ffffff', elements }
+}
+
+describe('ReadOnlySlide', () => {
+  it("renders a slide's image + overlay non-interactively (no interactive chrome)", async () => {
+    const { container } = render(
+      <ReadOnlySlide
+        slide={makeSlide([imgEl, overlayEl])}
+        width={1080}
+        height={1080}
+        scale={0.5}
+        resolveImageSrc={(el) => el.src}
+        compileOverlay={vi.fn(async () => () => null)}
+      />,
+    )
+
+    // Image element renders.
+    const img = await waitFor(() => {
+      const el = container.querySelector('[data-element-id="el-img"]') as HTMLElement
+      if (!el) throw new Error('image wrapper not yet rendered')
+      return el
+    })
+
+    // Non-interactive: the canvas root must not advertise interactivity, and the
+    // element wrappers must not receive pointer events (no selection chrome).
+    expect(container.querySelector('[data-interactive]')).toBeNull()
+    expect(img.style.pointerEvents).toBe('none')
+
+    // No resize / rotate handles rendered in read-only mode.
+    expect(container.querySelector('[data-testid="rotate-handle"]')).toBeNull()
+    expect(container.querySelector('[data-testid="resize-handle-nw"]')).toBeNull()
+  })
+
+  it('applies the explicit scale when provided', async () => {
+    const { container } = render(
+      <ReadOnlySlide
+        slide={makeSlide([imgEl])}
+        width={1080}
+        height={1080}
+        scale={0.5}
+        resolveImageSrc={(el) => el.src}
+      />,
+    )
+    // displayW = width * scale = 1080 * 0.5 = 540.
+    await waitFor(() => {
+      const inner = container.querySelector('[data-element-id="el-img"]') as HTMLElement
+      if (!inner) throw new Error('not rendered')
+    })
+    const canvas = container.querySelector('div > div') as HTMLElement
+    // The SlideCanvas root sets width to displayW; find a node sized 540px.
+    const sized = Array.from(container.querySelectorAll('div')).some(
+      (d) => (d as HTMLElement).style.width === '540px',
+    )
+    expect(sized).toBe(true)
+    expect(canvas).toBeTruthy()
+  })
+
+  it('measures the parent and applies a fitted scale when autoFit is on', async () => {
+    const { container } = render(
+      <ReadOnlySlide
+        slide={makeSlide([imgEl])}
+        width={1080}
+        height={1080}
+        autoFit
+        resolveImageSrc={(el) => el.src}
+      />,
+    )
+
+    // A ResizeObserver was created and is observing the root.
+    await waitFor(() => expect(roInstances.length).toBeGreaterThan(0))
+    const ro = roInstances[0]
+    expect(ro.el).not.toBeNull()
+
+    // Drive the observer: parent of the root is 540x540 → fit = 540/1080 = 0.5.
+    const root = ro.el as HTMLElement
+    Object.defineProperty(root, 'clientWidth', { value: 540, configurable: true })
+    Object.defineProperty(root, 'clientHeight', { value: 540, configurable: true })
+    ro.cb([], ro as unknown as ResizeObserver)
+
+    // After measuring, SlideCanvas renders at displayW = 1080 * 0.5 = 540.
+    await waitFor(() => {
+      const sized = Array.from(container.querySelectorAll('div')).some(
+        (d) => (d as HTMLElement).style.width === '540px',
+      )
+      expect(sized).toBe(true)
+    })
+  })
+})

package/src/carousel/__tests__/SlideCanvasCrop.test.tsx

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, waitFor } from '@testing-library/react'
+import type { ImageElement, Slide } from '../../types'
+import SlideCanvas from '../SlideCanvas'
+
+beforeEach(() => {
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+function makeSlide(el: ImageElement): Slide {
+  return { id: 'slide-0', base_color: '#ffffff', elements: [el] }
+}
+
+describe('SlideCanvas crop display', () => {
+  it('renders the oversized-cover crop variant when element.crop is present (non-interactive)', async () => {
+    const el: ImageElement = {
+      id: 'el-img',
+      type: 'image',
+      src: 'a.png',
+      x: 0,
+      y: 0,
+      w: 200,
+      h: 200,
+      rotation: 0,
+      crop: { x: 0.25, y: 0.1, w: 0.5, h: 0.5 },
+    }
+    const { container } = render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        resolveImageSrc={(e) => e.src}
+      />,
+    )
+
+    const img = await waitFor(() => {
+      const found = container.querySelector('[data-element-id="el-img"] img') as HTMLImageElement
+      if (!found) throw new Error('img not rendered')
+      return found
+    })
+
+    // Oversized cover: width = 100/cw = 200%, height = 100/ch = 200%.
+    expect(img.style.width).toBe('200%')
+    expect(img.style.height).toBe('200%')
+    // marginLeft = -cx*100/cw = -0.25*100/0.5 = -50%; marginTop = -0.1*100/0.5 = -20%.
+    expect(img.style.marginLeft).toBe('-50%')
+    expect(img.style.marginTop).toBe('-20%')
+    // Tailwind-preflight defeat.
+    expect(img.style.maxWidth).toBe('none')
+    expect(img.style.maxHeight).toBe('none')
+
+    // The crop wrapper clips overflow.
+    const wrapper = img.parentElement as HTMLElement
+    expect(wrapper.style.overflow).toBe('hidden')
+  })
+
+  it('renders plain cover (no crop wrapper) when element.crop is absent', async () => {
+    const el: ImageElement = {
+      id: 'el-img',
+      type: 'image',
+      src: 'a.png',
+      x: 0,
+      y: 0,
+      w: 200,
+      h: 200,
+      rotation: 0,
+    }
+    const { container } = render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        resolveImageSrc={(e) => e.src}
+      />,
+    )
+
+    const img = await waitFor(() => {
+      const found = container.querySelector('[data-element-id="el-img"] img') as HTMLImageElement
+      if (!found) throw new Error('img not rendered')
+      return found
+    })
+    expect(img.style.objectFit).toBe('cover')
+    expect(img.style.width).toBe('100%')
+    expect(img.style.height).toBe('100%')
+  })
+})

package/src/carousel/__tests__/SlideCanvasFonts.test.tsx

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, waitFor } from '@testing-library/react'
+import type { OverlayElement, Slide } from '../../types'
+
+// Spy on the shared font loader so we can assert the carousel overlay path
+// invokes it with the element's googleFonts list (unit-level — we do not assert
+// actual font bytes load in jsdom).
+const { ensureGoogleFontsLoaded } = vi.hoisted(() => ({ ensureGoogleFontsLoaded: vi.fn() }))
+vi.mock('../../lib/google-fonts', () => ({ ensureGoogleFontsLoaded }))
+
+import SlideCanvas from '../SlideCanvas'
+
+beforeEach(() => {
+  ensureGoogleFontsLoaded.mockClear()
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+function makeSlide(el: OverlayElement): Slide {
+  return { id: 'slide-0', base_color: '#ffffff', elements: [el] }
+}
+
+describe('SlideCanvas carousel overlay Google Fonts', () => {
+  it('loads an overlay element’s googleFonts via the shared helper', async () => {
+    const el: OverlayElement = {
+      id: 'el-ov',
+      type: 'overlay',
+      overlay: { template: '/overlays/lp-text.jsx', props: { text: 'Hola' } },
+      frame: 0,
+      x: 0,
+      y: 0,
+      w: 400,
+      h: 120,
+      rotation: 0,
+      googleFonts: ['Syne:wght@800', 'Inter:wght@400'],
+    }
+    render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        compileOverlay={vi.fn(async () => () => null)}
+      />,
+    )
+
+    await waitFor(() =>
+      expect(ensureGoogleFontsLoaded).toHaveBeenCalledWith(['Syne:wght@800', 'Inter:wght@400']),
+    )
+  })
+
+  it('does not throw when an overlay element has no googleFonts', async () => {
+    const el: OverlayElement = {
+      id: 'el-ov',
+      type: 'overlay',
+      overlay: { template: '/overlays/lp-text.jsx', props: { text: 'Hola' } },
+      frame: 0,
+      x: 0,
+      y: 0,
+      w: 400,
+      h: 120,
+      rotation: 0,
+    }
+    render(
+      <SlideCanvas
+        slide={makeSlide(el)}
+        width={1080}
+        height={1080}
+        interactive={false}
+        scale={1}
+        compileOverlay={vi.fn(async () => () => null)}
+      />,
+    )
+    // Helper is still invoked (with undefined) — it no-ops internally.
+    await waitFor(() => expect(ensureGoogleFontsLoaded).toHaveBeenCalledWith(undefined))
+  })
+})

package/src/index.ts

@@ -132,3 +132,5 @@ export { default as VideoEditor } from './video/VideoEditor'
 // components render SlideCanvas thumbnails and wrap overlays in the boundary.
 export { default as SlideCanvas, resolveAsset } from './carousel/SlideCanvas'
 export { default as OverlayErrorBoundary } from './carousel/OverlayErrorBoundary'
+export { default as ReadOnlySlide } from './carousel/ReadOnlySlide'
+export type { ReadOnlySlideProps } from './carousel/ReadOnlySlide'

package/src/lib/google-fonts.ts

@@ -0,0 +1,28 @@
+// Shared Google Fonts loader.
+//
+// Injects a Google Fonts stylesheet <link> for the declared family specs so the
+// editor's preview/render uses the same glyphs and metrics the renderer
+// (bundle.js) fetches. Used by both the video overlay layer and the carousel
+// overlay render path. Resilient by design: a font-load failure must never
+// break the render (we only append a <link>; the browser handles the fetch).
+
+// Track Google Fonts URLs already injected so we don't add the same <link>
+// twice when multiple overlays declare overlapping fonts. Keyed by the full
+// stylesheet URL — the same URL never produces a duplicate fetch from
+// Chromium regardless, but the duplicate <link> tags would still clutter
+// document.head across long editing sessions.
+const __injectedFontUrls = new Set<string>()
+
+export function ensureGoogleFontsLoaded(googleFonts: string[] | undefined): void {
+  if (!googleFonts?.length) return
+  // Match the format bundle.js uses for the render pipeline so preview and
+  // render fetch identical CSS (and identical glyphs / metrics).
+  const url = `https://fonts.googleapis.com/css2?${googleFonts.map((f) => `family=${f}`).join('&')}&display=swap`
+  if (__injectedFontUrls.has(url)) return
+  __injectedFontUrls.add(url)
+  if (typeof document === 'undefined') return
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = url
+  document.head.appendChild(link)
+}

package/src/schema.ts

@@ -157,6 +157,13 @@ export interface OverlayElement {
   w: number
   h: number
   rotation: number
+  /**
+   * Optional Google Fonts family specs (e.g. ["Syne:wght@800"]) the overlay
+   * renders with. Mirrors the video-side `VisualItem.googleFonts`. The carousel
+   * overlay render path injects these so the preview uses the same glyphs and
+   * metrics as the renderer; absent = no custom fonts loaded.
+   */
+  googleFonts?: string[]
 }
 
 export type CarouselElement = ImageElement | OverlayElement

package/src/types.ts

@@ -406,6 +406,26 @@ export interface CarouselEditorProps<P extends Project = Project> {
   theme?: EditorTheme
   slots?: EditorSlots
   readOnly?: boolean
+  /**
+   * Editor-only set of element ids to hide from the interactive canvas. The host
+   * owns this state; the package never persists it (hidden elements are omitted
+   * from the canvas render only, never from `saveProject`). Lets a host
+   * temporarily hide a scrim/background to position overlays beneath it.
+   */
+  hiddenElementIds?: string[]
+  /**
+   * Invoked when the user toggles the selected element's editor-visibility via
+   * the property-panel eye button. The host updates its hidden-set and reflects
+   * it back through `hiddenElementIds`. Absent → no eye toggle is rendered.
+   */
+  onToggleElementVisibility?: (elementId: string) => void
+  /**
+   * Invoked whenever the selected element changes — with the element, or `null`
+   * when selection clears. Lets a host drive selection-aware chrome (e.g. a
+   * "regenerate image" action in a toolbar slot that targets the current
+   * selection). The package keeps owning selection state.
+   */
+  onSelectionChange?: (element: CarouselElement | null) => void
 }
 
 /**

package/src/video/preview/OverlayItemsLayer.tsx

@@ -3,6 +3,7 @@ import type { EditorProject as Project, VisualItem } from '../../schema'
 import type { OverlayFactory } from '../../types'
 import OverlayErrorBoundary from '../../carousel/OverlayErrorBoundary'
 import { getOverlayDesignCanvas } from '../design-canvas'
+import { ensureGoogleFontsLoaded } from '../../lib/google-fonts'
 import type { Corner } from './useDragOverlay'
 import type { useDragOverlay } from './useDragOverlay'
 
@@ -104,26 +105,6 @@ interface CustomOverlayProps {
   fileUrl: (path: string) => string
 }
 
-// Track Google Fonts URLs already injected so we don't add the same <link>
-// twice when multiple overlays declare overlapping fonts. Keyed by the full
-// stylesheet URL — the same URL never produces a duplicate fetch from
-// Chromium regardless, but the duplicate <link> tags would still clutter
-// document.head across long editing sessions.
-const __injectedFontUrls = new Set<string>()
-
-function ensureGoogleFontsLoaded(googleFonts: string[] | undefined) {
-  if (!googleFonts?.length) return
-  // Match the format bundle.js uses for the render pipeline so preview and
-  // render fetch identical CSS (and identical glyphs / metrics).
-  const url = `https://fonts.googleapis.com/css2?${googleFonts.map(f => `family=${f}`).join('&')}&display=swap`
-  if (__injectedFontUrls.has(url)) return
-  __injectedFontUrls.add(url)
-  const link = document.createElement('link')
-  link.rel = 'stylesheet'
-  link.href = url
-  document.head.appendChild(link)
-}
-
 function CustomOverlay({
   src,
   props,