@bycrux/editor 0.8.6 → 0.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "private": false,
   "type": "module",
   "exports": {

package/src/ControlsInfoModal.tsx

@@ -0,0 +1,157 @@
+import { useEffect } from 'react'
+import { X } from 'lucide-react'
+
+/** A single control/shortcut row. `keys` renders as <kbd> chips; omit for a pure gesture. */
+export interface ControlEntry {
+  keys?: string[]
+  label: string
+}
+
+export interface ControlSection {
+  heading: string
+  entries: ControlEntry[]
+}
+
+export interface ControlsInfoModalProps {
+  title: string
+  sections: ControlSection[]
+  onClose: () => void
+}
+
+/**
+ * Read-only "how to drive this editor" modal. Content is passed in per editor
+ * (video vs carousel) so this component stays a dumb, themed renderer. Matches
+ * the backdrop/Esc/close conventions of the other editor modals (TranscriptModal
+ * et al.) and uses the shared `--editor-*` theme tokens.
+ */
+export default function ControlsInfoModal({ title, sections, onClose }: ControlsInfoModalProps) {
+  useEffect(() => {
+    const onKey = (e: globalThis.KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={title}
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm"
+      onClick={onClose}
+    >
+      <div
+        className="relative mx-4 flex max-h-[80vh] w-full max-w-md flex-col overflow-hidden rounded-lg border shadow-2xl"
+        style={{
+          background: 'var(--editor-surface)',
+          borderColor: 'var(--editor-border)',
+          color: 'var(--editor-text)',
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div
+          className="flex shrink-0 items-center justify-between border-b px-4 py-3"
+          style={{ borderColor: 'var(--editor-border)' }}
+        >
+          <h2 className="text-sm font-semibold">{title}</h2>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close"
+            className="cursor-pointer opacity-60 transition-opacity hover:opacity-100"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="space-y-4 overflow-y-auto px-4 py-3">
+          {sections.map((section) => (
+            <div key={section.heading}>
+              <p className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide opacity-50">
+                {section.heading}
+              </p>
+              <ul className="space-y-1.5">
+                {section.entries.map((entry, i) => (
+                  <li key={i} className="flex items-start justify-between gap-3 text-xs">
+                    <span className="opacity-80">{entry.label}</span>
+                    {entry.keys && entry.keys.length > 0 && (
+                      <span className="flex shrink-0 items-center gap-1">
+                        {entry.keys.map((k, j) => (
+                          <kbd
+                            key={j}
+                            className="rounded border px-1.5 py-0.5 font-mono text-[10px] leading-none"
+                            style={{ borderColor: 'var(--editor-border)', background: 'var(--editor-bg)' }}
+                          >
+                            {k}
+                          </kbd>
+                        ))}
+                      </span>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** Controls reference for the video/timeline editor. Sourced from VideoEditor's
+ *  key handler (S / ⌘Z), the track-controls toolbar, and PreviewPlayer's
+ *  on-canvas transform (drag / corner-drag / scroll / rotate). */
+export const VIDEO_CONTROLS: ControlSection[] = [
+  {
+    heading: 'Preview',
+    entries: [
+      { label: 'Drag to move the selected clip or overlay' },
+      { label: 'Corner-drag or scroll to scale it' },
+      { label: 'Drag the rotate handle to turn an overlay' },
+    ],
+  },
+  {
+    heading: 'Timeline',
+    entries: [
+      { label: 'Drag a clip to reposition it' },
+      { label: "Drag a clip's edge to trim it" },
+      { label: 'Select a clip, then click ⓘ to inspect it' },
+    ],
+  },
+  {
+    heading: 'Toolbar',
+    entries: [
+      { label: 'Ripple: edits close the gap instead of leaving it' },
+      { label: 'Crop source: non-destructively crop the selected clip' },
+    ],
+  },
+  {
+    heading: 'Keyboard',
+    entries: [
+      { keys: ['S'], label: 'Split at the playhead' },
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+    ],
+  },
+]
+
+/** Controls reference for the carousel editor. Sourced from CarouselEditor's key
+ *  handlers (undo/redo, Delete) and the canvas gesture hints. */
+export const CAROUSEL_CONTROLS: ControlSection[] = [
+  {
+    heading: 'Canvas',
+    entries: [
+      { label: 'Drag an element to reposition it' },
+      { label: 'Resize or rotate it via the handles' },
+      { label: 'Double-click text to edit it' },
+    ],
+  },
+  {
+    heading: 'Keyboard',
+    entries: [
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+      { keys: ['⌘/Ctrl', '⇧', 'Z'], label: 'Redo' },
+      { keys: ['Delete'], label: 'Remove the selected element' },
+    ],
+  },
+]

package/src/__tests__/ControlsInfoModal.test.tsx

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render, screen, fireEvent, cleanup } from '@testing-library/react'
+import ControlsInfoModal, {
+  VIDEO_CONTROLS,
+  CAROUSEL_CONTROLS,
+  type ControlSection,
+} from '../ControlsInfoModal'
+
+afterEach(() => cleanup())
+
+const SECTIONS: ControlSection[] = [
+  {
+    heading: 'Canvas',
+    entries: [
+      { label: 'Drag an element to reposition it' },
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+    ],
+  },
+]
+
+describe('ControlsInfoModal', () => {
+  it('renders the title, section headings, entry labels, and kbd chips', () => {
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={vi.fn()} />)
+
+    expect(screen.getByRole('dialog', { name: 'Editor controls' })).toBeTruthy()
+    expect(screen.getByText('Canvas')).toBeTruthy()
+    expect(screen.getByText('Drag an element to reposition it')).toBeTruthy()
+    // Keys render as individual <kbd> chips.
+    expect(screen.getByText('⌘/Ctrl').tagName).toBe('KBD')
+    expect(screen.getByText('Z').tagName).toBe('KBD')
+  })
+
+  it('closes on Escape', () => {
+    const onClose = vi.fn()
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={onClose} />)
+    fireEvent.keyDown(window, { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes on backdrop click but not on panel click', () => {
+    const onClose = vi.fn()
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={onClose} />)
+
+    // Click inside the panel — should NOT close.
+    fireEvent.click(screen.getByText('Canvas'))
+    expect(onClose).not.toHaveBeenCalled()
+
+    // Click the backdrop (the dialog root) — should close.
+    fireEvent.click(screen.getByRole('dialog'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('ships real control content for both editors', () => {
+    // Guards against an empty/placeholder content regression.
+    const videoLabels = VIDEO_CONTROLS.flatMap((s) => s.entries.map((e) => e.label))
+    const carouselLabels = CAROUSEL_CONTROLS.flatMap((s) => s.entries.map((e) => e.label))
+    expect(videoLabels).toEqual(expect.arrayContaining(['Split at the playhead']))
+    expect(carouselLabels).toEqual(expect.arrayContaining(['Double-click text to edit it']))
+    expect(VIDEO_CONTROLS.length).toBeGreaterThan(0)
+    expect(CAROUSEL_CONTROLS.length).toBeGreaterThan(0)
+  })
+})

package/src/carousel/CarouselEditor.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import { RefreshCw, AlertCircle, Download } from 'lucide-react'
+import { RefreshCw, AlertCircle, Download, Info } from 'lucide-react'
 import type { Project, Slide, CarouselElement, ImageElement, CarouselEditorProps, OverlayFactory } from '../types'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { useProjectState } from '../state/use-project-state'
@@ -7,6 +7,7 @@ import SlideCanvas from './SlideCanvas'
 import SlidePropertyPanel from './SlidePropertyPanel'
 import AddElementMenu from './AddElementMenu'
 import CarouselRenderModal from './CarouselRenderModal'
+import ControlsInfoModal, { CAROUSEL_CONTROLS } from '../ControlsInfoModal'
 import { Button } from '../ui'
 
 // Generic over the host's concrete project type `P` (default = the package's
@@ -167,6 +168,7 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
 
   const [skillPath, setSkillPath] = useState<string | null>(null)
   const [copied, setCopied] = useState(false)
+  const [showControls, setShowControls] = useState(false)
   const [refreshing, setRefreshing] = useState(false)
   const [refreshState, setRefreshState] = useState<'idle' | 'err'>('idle')
   const [rendering, setRendering] = useState(false)
@@ -505,9 +507,20 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
                 hiddenElementIds={hiddenElementIds}
               />
             </div>
-            <p className="flex-shrink-0 text-xs text-[var(--editor-text)]/60 text-center max-w-md">
-              Drag to reposition, resize/rotate via handles, double-click text to edit. Cmd/Ctrl+Z to undo.
-            </p>
+            <div className="flex-shrink-0 flex items-center justify-center gap-1.5 text-xs text-[var(--editor-text)]/60 max-w-md">
+              <span className="text-center">
+                Drag to reposition, resize/rotate via handles, double-click text to edit. Cmd/Ctrl+Z to undo.
+              </span>
+              <button
+                type="button"
+                onClick={() => setShowControls(true)}
+                title="Editor controls & shortcuts"
+                aria-label="Editor controls & shortcuts"
+                className="shrink-0 cursor-pointer opacity-60 transition-opacity hover:opacity-100"
+              >
+                <Info size={13} />
+              </button>
+            </div>
           </>
         ) : (
           <div className="text-[var(--editor-text)]/40 text-sm">No slides yet. Add one in the left panel.</div>
@@ -566,6 +579,14 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
         </div>
       )}
 
+      {showControls && (
+        <ControlsInfoModal
+          title="Editor controls"
+          sections={CAROUSEL_CONTROLS}
+          onClose={() => setShowControls(false)}
+        />
+      )}
+
       {renderOpen && (
         <CarouselRenderModal
           projectId={project.id}

package/src/carousel/CarouselRenderModal.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import type { EditorAdapter, Project } from '../types'
+import type { EditorAdapter, Project, RenderStatus } from '../types'
 
 interface CarouselRenderModalProps {
   projectId: string
@@ -21,10 +21,42 @@ interface CarouselRenderModalProps {
   exportActions?: ReactNode
 }
 
+/** Promoted render output (R2-presigned), as carried by `RenderStatus.media`. */
+type RenderMedia = NonNullable<RenderStatus['media']>[number]
+
+/** A rendered slide ready to display: a direct URL + its filename caption. */
+interface SlideView { url: string; filename: string }
+
+const POLL_INTERVAL_MS = 2500
+
+/**
+ * Consecutive status-poll failures tolerated before the modal declares the
+ * render failed. A transient network blip (a Cloudflare-tunnel hiccup, a backend
+ * redeploy, a flaky hop) must not be mistaken for a render failure — the render
+ * keeps running server-side. ~12 × 2.5s ≈ 30s of continuous unreachability
+ * before giving up. An explicit backend `error` status is still terminal.
+ * Mirrors `video/RenderModal.tsx`.
+ */
+const MAX_POLL_FAILURES = 12
+
 function slideFile(index: number): string {
   return `slide_${String(index + 1).padStart(2, '0')}.png`
 }
 
+/**
+ * Order promoted media into slide order for the gallery. Hub's
+ * `promoteRenderOutputs` returns media unordered and may include non-slide
+ * outputs (e.g. `manifest.json`), so keep only `slide_NN.png` and sort by the
+ * numeric index.
+ */
+function slidesFromMedia(media: RenderMedia[]): SlideView[] {
+  return media
+    .map((m) => ({ m, match: /^slide_0*(\d+)\.png$/i.exec(m.filename) }))
+    .filter((x): x is { m: RenderMedia; match: RegExpExecArray } => x.match !== null)
+    .sort((a, b) => Number(a.match[1]) - Number(b.match[1]))
+    .map(({ m }) => ({ url: m.url, filename: m.filename }))
+}
+
 function LogLine({ text }: { text: string }) {
   const t = text.replace(/^\[render\]\s*/, '')
   let color = 'text-[var(--editor-text)]/60'
@@ -46,46 +78,126 @@ function LogLine({ text }: { text: string }) {
 export default function CarouselRenderModal({ projectId, adapter, slidesCount, resolution, onClose, onCancel, exportActions }: CarouselRenderModalProps) {
   const [logs, setLogs]         = useState<string[]>([])
   const [status, setStatus]     = useState<'running' | 'done' | 'error'>('running')
+  const [media, setMedia]       = useState<RenderMedia[] | null>(null)
   const [outputDir, setOutDir]  = useState<string | null>(null)
   const [errorMsg, setError]    = useState<string | null>(null)
   const logRef                  = useRef<HTMLDivElement>(null)
   const cancelledRef            = useRef(false)
   const unmountedRef            = useRef(false)
   const cleanupTimerRef         = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const pollTimerRef            = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  // Data-transport decision: does this adapter expose the poll-based render API?
+  // Hub clients (async-kick backend) do; the montaj-native desktop host doesn't
+  // and falls back to the SSE `adapter.render()` stream below.
+  const usePolling = !!(adapter.renderAsync && adapter.getRenderStatus)
 
   useEffect(() => {
     // StrictMode-safe render trigger — see RenderModal.tsx for the long-form
-    // comment.
+    // comment. Triggering a render is non-idempotent (spawns a subprocess), so
+    // defer teardown and rescue it if the next mount fires within the same tick.
     if (cleanupTimerRef.current !== null) {
       clearTimeout(cleanupTimerRef.current)
       cleanupTimerRef.current = null
       unmountedRef.current = false
+      cancelledRef.current = false
       return scheduleCleanup
     }
 
     unmountedRef.current = false
     cancelledRef.current = false
-    ;(async () => {
+
+    void (async () => {
       try {
-        for await (const ev of adapter.render(projectId)) {
-          if (cancelledRef.current || unmountedRef.current) break
-          if (ev.type === 'log') setLogs(l => [...l, ev.message])
-          else if (ev.type === 'done') { setOutDir(ev.outputPath); setStatus('done') }
-          else if (ev.type === 'error') { setError(ev.message); setStatus('error') }
+        if (usePolling) {
+          // Async, poll-based render: kick once, then poll status until terminal.
+          // The backend's POST render returns immediately ({status:'running'})
+          // and the render runs detached — so we follow it via getRenderStatus
+          // instead of a (now non-existent) SSE stream. This is the fix for the
+          // modal hanging forever on "Starting render engine…".
+          await adapter.renderAsync!(projectId)
+          if (unmountedRef.current || cancelledRef.current) return
+
+          let pollFailures = 0
+          const tick = async () => {
+            if (unmountedRef.current || cancelledRef.current) return
+            let snap: RenderStatus
+            try {
+              snap = await adapter.getRenderStatus!(projectId)
+              pollFailures = 0
+            } catch (e) {
+              if (unmountedRef.current || cancelledRef.current) return
+              // Transient unreachability must NOT read as a render failure — the
+              // render is still running server-side. Keep polling; only give up
+              // after MAX_POLL_FAILURES consecutive failures. An explicit
+              // { status: 'error' } reply is still terminal (handled below).
+              pollFailures += 1
+              if (pollFailures >= MAX_POLL_FAILURES) {
+                stopPolling()
+                setError(e instanceof Error ? e.message : String(e))
+                setStatus('error')
+              }
+              return
+            }
+            if (unmountedRef.current || cancelledRef.current) return
+
+            if (snap.media) setMedia(snap.media)
+
+            if (snap.status === 'done') {
+              stopPolling()
+              setMedia(snap.media ?? null)
+              setStatus('done')
+            } else if (snap.status === 'error') {
+              stopPolling()
+              setError(snap.error ?? 'Render failed.')
+              setStatus('error')
+            } else if (snap.status === 'idle') {
+              // We just kicked the render, so a job exists server-side; an 'idle'
+              // reply means the sidecar lost it (e.g. restarted mid-render).
+              // Without this we'd poll forever with no progress.
+              stopPolling()
+              setError('The render was interrupted on the server. Please try again.')
+              setStatus('error')
+            }
+          }
+
+          // First poll immediately, then on the interval.
+          await tick()
+          if (unmountedRef.current || cancelledRef.current) return
+          pollTimerRef.current = setInterval(() => { void tick() }, POLL_INTERVAL_MS)
+        } else {
+          // Fallback for hosts without the poll API (montaj-native desktop):
+          // consume the SSE render stream and accumulate log lines.
+          for await (const ev of adapter.render(projectId)) {
+            if (cancelledRef.current || unmountedRef.current) break
+            if (ev.type === 'log') setLogs(l => [...l, ev.message])
+            else if (ev.type === 'done') { setOutDir(ev.outputPath); setStatus('done') }
+            else if (ev.type === 'error') { setError(ev.message); setStatus('error') }
+          }
         }
       } catch (e) {
         if (!cancelledRef.current && !unmountedRef.current) {
-          setError(String(e)); setStatus('error')
+          setError(e instanceof Error ? e.message : String(e))
+          setStatus('error')
         }
       }
     })()
+
     return scheduleCleanup
 
+    function stopPolling() {
+      if (pollTimerRef.current !== null) {
+        clearInterval(pollTimerRef.current)
+        pollTimerRef.current = null
+      }
+    }
+
     function scheduleCleanup() {
       cleanupTimerRef.current = setTimeout(() => {
         cleanupTimerRef.current = null
         unmountedRef.current = true
         cancelledRef.current = true
+        stopPolling()
       }, 0)
     }
   }, [projectId, adapter])
@@ -108,7 +220,18 @@ export default function CarouselRenderModal({ projectId, adapter, slidesCount, r
   }
 
   // ── Done state — gallery + zip download ─────────────────────────────────
-  if (status === 'done' && outputDir) {
+  if (status === 'done') {
+    // Prefer the promoted R2 media (poll path); fall back to workspace paths
+    // resolved via fileUrl (SSE path).
+    const slides: SlideView[] = media
+      ? slidesFromMedia(media)
+      : outputDir
+        ? Array.from({ length: slidesCount }).map((_, i) => {
+            const file = slideFile(i)
+            return { url: adapter.fileUrl(`${outputDir}/${file}`), filename: file }
+          })
+        : []
+
     // Portal to document.body (see RenderModal): a transformed host ancestor
     // would otherwise trap this `fixed` overlay and center the panel off-screen.
     return createPortal(
@@ -117,35 +240,35 @@ export default function CarouselRenderModal({ projectId, adapter, slidesCount, r
 
           {/* Left — slide gallery */}
           <div className="flex-1 bg-black flex items-center justify-center overflow-auto p-8">
-            <div
-              className="grid gap-4 w-full max-w-6xl"
-              style={{ gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))' }}
-            >
-              {Array.from({ length: slidesCount }).map((_, i) => {
-                const file = slideFile(i)
-                const url = adapter.fileUrl(`${outputDir}/${file}`)
-                return (
+            {slides.length > 0 ? (
+              <div
+                className="grid gap-4 w-full max-w-6xl"
+                style={{ gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))' }}
+              >
+                {slides.map((slide, i) => (
                   <a
-                    key={i}
-                    href={url}
+                    key={slide.filename}
+                    href={slide.url}
                     target="_blank"
                     rel="noreferrer"
                     className="group relative block rounded-lg overflow-hidden border border-[var(--editor-border)] hover:border-[var(--editor-accent)] transition-colors bg-[var(--editor-surface)]"
                   >
                     <img
-                      src={url}
-                      alt={file}
+                      src={slide.url}
+                      alt={slide.filename}
                       className="block w-full h-auto"
                       style={{ aspectRatio: `${resolution[0]} / ${resolution[1]}` }}
                     />
                     <div className="absolute bottom-0 left-0 right-0 px-2 py-1.5 bg-black text-[11px] text-[var(--editor-text)] font-mono flex justify-between">
                       <span>#{String(i + 1).padStart(2, '0')}</span>
-                      <span className="text-[var(--editor-text)]/60">{file}</span>
+                      <span className="text-[var(--editor-text)]/60">{slide.filename}</span>
                     </div>
                   </a>
-                )
-              })}
-            </div>
+                ))}
+              </div>
+            ) : (
+              <p className="text-sm text-[var(--editor-text)]/60">Render complete.</p>
+            )}
           </div>
 
           {/* Right — info panel */}
@@ -156,7 +279,7 @@ export default function CarouselRenderModal({ projectId, adapter, slidesCount, r
                 <div>
                   <p className="text-sm font-semibold text-[var(--editor-text)]">Render complete</p>
                   <p className="text-xs text-[var(--editor-text)]/60">
-                    {slidesCount} slide{slidesCount === 1 ? '' : 's'} ready.
+                    {slides.length || slidesCount} slide{(slides.length || slidesCount) === 1 ? '' : 's'} ready.
                   </p>
                 </div>
               </div>
@@ -164,7 +287,6 @@ export default function CarouselRenderModal({ projectId, adapter, slidesCount, r
             </div>
 
             <div className="flex flex-col gap-3 p-5 flex-1">
-              <p className="text-xs font-mono text-[var(--editor-text)]/60 break-all leading-relaxed">{outputDir}</p>
               {exportActions}
               <button
                 onClick={onClose}
@@ -180,7 +302,9 @@ export default function CarouselRenderModal({ projectId, adapter, slidesCount, r
     )
   }
 
-  // ── Running / error state — log readout ─────────────────────────────────
+  // ── Running / error state ───────────────────────────────────────────────
+  // Poll transport carries no per-line logs, so show a spinner + status text;
+  // the SSE transport (montaj-native) streams logs into the log panel.
   return createPortal(
     <div className="fixed inset-0 z-50 flex items-center justify-center bg-black">
       <div className="w-full max-w-3xl bg-[var(--editor-surface)] border border-[var(--editor-border)] rounded-xl shadow-2xl flex flex-col overflow-hidden">
@@ -200,29 +324,45 @@ export default function CarouselRenderModal({ projectId, adapter, slidesCount, r
           )}
         </div>
 
-        <div className="relative">
-          <button
-            onClick={() => navigator.clipboard.writeText(logs.join('\n') + (errorMsg ? '\n' + errorMsg : ''))}
-            className="absolute top-2 right-2 z-10 text-[10px] px-2 py-0.5 rounded bg-[var(--editor-surface)] border border-[var(--editor-border)] text-[var(--editor-text)]/60 hover:text-[var(--editor-text)] hover:border-[var(--editor-accent)] transition-colors"
-            title="Copy logs"
-          >
-            Copy
-          </button>
-          <div
-            ref={logRef}
-            className="h-96 overflow-y-auto px-4 py-3 font-mono text-[11px] text-[var(--editor-text)] bg-[var(--editor-bg)] flex flex-col gap-0.5"
-          >
-            {logs.length === 0 && status === 'running' && (
-              <span className="text-[var(--editor-text)]/40 italic">Starting render engine…</span>
-            )}
-            {logs.map((line, i) => (
-              <LogLine key={i} text={line} />
-            ))}
-            {status === 'error' && errorMsg && (
-              <span className="text-red-400 mt-1">{errorMsg}</span>
+        {usePolling ? (
+          <div className="px-5 py-8 flex flex-col items-center justify-center gap-4 min-h-[12rem]">
+            {status === 'running' ? (
+              <>
+                <span className="w-6 h-6 rounded-full border-2 border-amber-400 border-t-transparent animate-spin" />
+                <p className="text-sm text-[var(--editor-text)]/70">Rendering slides…</p>
+                <p className="text-xs text-[var(--editor-text)]/50">This can take a moment.</p>
+              </>
+            ) : (
+              <p className="text-sm text-red-400 whitespace-pre-wrap break-words text-center">
+                {errorMsg ?? 'Render failed.'}
+              </p>
             )}
           </div>
-        </div>
+        ) : (
+          <div className="relative">
+            <button
+              onClick={() => navigator.clipboard.writeText(logs.join('\n') + (errorMsg ? '\n' + errorMsg : ''))}
+              className="absolute top-2 right-2 z-10 text-[10px] px-2 py-0.5 rounded bg-[var(--editor-surface)] border border-[var(--editor-border)] text-[var(--editor-text)]/60 hover:text-[var(--editor-text)] hover:border-[var(--editor-accent)] transition-colors"
+              title="Copy logs"
+            >
+              Copy
+            </button>
+            <div
+              ref={logRef}
+              className="h-96 overflow-y-auto px-4 py-3 font-mono text-[11px] text-[var(--editor-text)] bg-[var(--editor-bg)] flex flex-col gap-0.5"
+            >
+              {logs.length === 0 && status === 'running' && (
+                <span className="text-[var(--editor-text)]/40 italic">Starting render engine…</span>
+              )}
+              {logs.map((line, i) => (
+                <LogLine key={i} text={line} />
+              ))}
+              {status === 'error' && errorMsg && (
+                <span className="text-red-400 mt-1">{errorMsg}</span>
+              )}
+            </div>
+          </div>
+        )}
 
         <div className="flex items-center justify-end gap-2 px-5 py-3 border-t border-[var(--editor-border)]">
           {status === 'running' ? (

package/src/video/VideoEditor.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { Crop, Magnet } from 'lucide-react'
+import { Crop, Info, Magnet } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
 import { VideoSourceCropModal } from '../crop/VideoSourceCropModal'
+import ControlsInfoModal, { VIDEO_CONTROLS } from '../ControlsInfoModal'
 import { getOverlayDesignCanvas } from './design-canvas'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { applyCutToItem, applyCutToTracks, collapseGaps, splitAtTime } from './cuts'
@@ -287,6 +288,7 @@ function ReviewSurface<P extends Project>({
   const [selectedIds, setSelectedIds] = useState<string[]>([])
   const primarySelectedId = selectedIds[0] ?? null
   const [rippleMode, setRippleMode]   = useState(false)
+  const [showControls, setShowControls] = useState(false)
   // Source-crop mode: when on, the VideoSourceCropModal opens for the selected
   // tracks[0] video item. Cleared when selection changes.
   const [cropMode, setCropMode]       = useState(false)
@@ -463,8 +465,16 @@ function ReviewSurface<P extends Project>({
           )}
         </div>
 
-        {/* Track controls bar — split + ripple + render */}
+        {/* Track controls bar — info + split + ripple + render */}
         <div className="shrink-0 flex items-center justify-end gap-1.5 px-3 py-1 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
+          <button
+            onClick={() => setShowControls(true)}
+            title="Editor controls & shortcuts"
+            aria-label="Editor controls & shortcuts"
+            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)] mr-auto"
+          >
+            <Info size={12} />
+          </button>
           <button
             onClick={() => handleSplit()}
             title="Split at playhead (S) — selected item or all clips"
@@ -613,6 +623,15 @@ function ReviewSurface<P extends Project>({
         />
       )}
 
+      {/* Controls & shortcuts reference */}
+      {showControls && (
+        <ControlsInfoModal
+          title="Editor controls"
+          sections={VIDEO_CONTROLS}
+          onClose={() => setShowControls(false)}
+        />
+      )}
+
       {/* Render modal — adapter.render stream + host export controls */}
       {renderOpen && (
         <RenderModal