From d39963e9a47ad5aea361ccfbde8df39678c1988c Mon Sep 17 00:00:00 2001
From: cbaucom <chrisrb83@gmail.com>
Date: Wed, 10 Jun 2026 22:24:32 -0400
Subject: [PATCH 1/2] refactor(editor-shell): extract slide dialogs and
 persistence helpers

Split App.tsx below the architecture file-size cap by moving
TitleSlideDialog, SlideSettingsDialog, and slide JSON helpers into
dedicated modules. Behavior unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .claude/skills/composition-patterns/SKILL.md  |  42 +++
 .../rules/architecture-avoid-boolean-props.md | 100 ++++++
 .../rules/patterns-explicit-variants.md       | 100 ++++++
 .../rules/state-lift-state.md                 | 125 +++++++
 CLAUDE.md                                     |   2 +-
 src/editor-shell/App.tsx                      | 311 +-----------------
 src/editor-shell/SlideSettingsDialog.tsx      | 128 +++++++
 src/editor-shell/TitleSlideDialog.tsx         | 118 +++++++
 src/editor-shell/slidePersistence.ts          |  57 ++++
 9 files changed, 676 insertions(+), 307 deletions(-)
 create mode 100644 .claude/skills/composition-patterns/SKILL.md
 create mode 100644 .claude/skills/composition-patterns/rules/architecture-avoid-boolean-props.md
 create mode 100644 .claude/skills/composition-patterns/rules/patterns-explicit-variants.md
 create mode 100644 .claude/skills/composition-patterns/rules/state-lift-state.md
 create mode 100644 src/editor-shell/SlideSettingsDialog.tsx
 create mode 100644 src/editor-shell/TitleSlideDialog.tsx
 create mode 100644 src/editor-shell/slidePersistence.ts

diff --git a/.claude/skills/composition-patterns/SKILL.md b/.claude/skills/composition-patterns/SKILL.md
new file mode 100644
index 0000000..7c83494
--- /dev/null
+++ b/.claude/skills/composition-patterns/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: composition-patterns
+description: React composition patterns for the editor shell. Use when refactoring components with boolean prop proliferation, splitting large components, or designing flexible component APIs in src/editor-shell/.
+metadata:
+  tags: react, composition, architecture, editor-shell
+  source: vercel-labs/agent-skills (subset)
+---
+
+## When to use
+
+Load this skill before adding or refactoring UI in `src/editor-shell/`. Read `standards/react.md` and `standards/architecture.md` alongside these rules.
+
+Triggers:
+
+- A component file approaches or exceeds the 300-line cap
+- Adding boolean props to customize component behavior (`isEditing`, `showFooter`, etc.)
+- One component handles multiple slide/dialog/panel modes via conditionals
+- Sibling components need shared state (e.g. drag preview + storyboard grid)
+
+## Applicable rules (this project)
+
+Only three rules from the Vercel composition-patterns skill apply at current scale. Read the full rule file before implementing:
+
+| Priority | Rule | File |
+| -------- | ---- | ---- |
+| CRITICAL | Avoid boolean prop proliferation | [rules/architecture-avoid-boolean-props.md](rules/architecture-avoid-boolean-props.md) |
+| MEDIUM | Explicit variant components | [rules/patterns-explicit-variants.md](rules/patterns-explicit-variants.md) |
+| HIGH | Lift state into providers | [rules/state-lift-state.md](rules/state-lift-state.md) |
+
+## Not applicable yet
+
+Skip these until the codebase needs them:
+
+- `architecture-compound-components` — no shared compound context yet
+- `state-context-interface` / `state-decouple-implementation` — state still lives in App with callback props
+- `patterns-children-over-render-props` — no render-prop APIs
+- `react19-no-forwardref` — not using forwardRef
+
+## Local examples
+
+- `TitleSlideDialog` and `SlideSettingsDialog` are explicit variants (not one dialog with `isTitle` boolean)
+- App lifts state; dialogs receive data + callbacks — provider pattern becomes relevant when siblings outside the dialog need the same state
diff --git a/.claude/skills/composition-patterns/rules/architecture-avoid-boolean-props.md b/.claude/skills/composition-patterns/rules/architecture-avoid-boolean-props.md
new file mode 100644
index 0000000..ccee19c
--- /dev/null
+++ b/.claude/skills/composition-patterns/rules/architecture-avoid-boolean-props.md
@@ -0,0 +1,100 @@
+---
+title: Avoid Boolean Prop Proliferation
+impact: CRITICAL
+impactDescription: prevents unmaintainable component variants
+tags: composition, props, architecture
+---
+
+## Avoid Boolean Prop Proliferation
+
+Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
+component behavior. Each boolean doubles possible states and creates
+unmaintainable conditional logic. Use composition instead.
+
+**Incorrect (boolean props create exponential complexity):**
+
+```tsx
+function Composer({
+  onSubmit,
+  isThread,
+  channelId,
+  isDMThread,
+  dmId,
+  isEditing,
+  isForwarding,
+}: Props) {
+  return (
+    <form>
+      <Header />
+      <Input />
+      {isDMThread ? (
+        <AlsoSendToDMField id={dmId} />
+      ) : isThread ? (
+        <AlsoSendToChannelField id={channelId} />
+      ) : null}
+      {isEditing ? (
+        <EditActions />
+      ) : isForwarding ? (
+        <ForwardActions />
+      ) : (
+        <DefaultActions />
+      )}
+      <Footer onSubmit={onSubmit} />
+    </form>
+  )
+}
+```
+
+**Correct (composition eliminates conditionals):**
+
+```tsx
+// Channel composer
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Attachments />
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Thread composer - adds "also send to channel" field
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <AlsoSendToChannelField id={channelId} />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Edit composer - different footer actions
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+```
+
+Each variant is explicit about what it renders. We can share internals without
+sharing a single monolithic parent.
diff --git a/.claude/skills/composition-patterns/rules/patterns-explicit-variants.md b/.claude/skills/composition-patterns/rules/patterns-explicit-variants.md
new file mode 100644
index 0000000..56e32e8
--- /dev/null
+++ b/.claude/skills/composition-patterns/rules/patterns-explicit-variants.md
@@ -0,0 +1,100 @@
+---
+title: Create Explicit Component Variants
+impact: MEDIUM
+impactDescription: self-documenting code, no hidden conditionals
+tags: composition, variants, architecture
+---
+
+## Create Explicit Component Variants
+
+Instead of one component with many boolean props, create explicit variant
+components. Each variant composes the pieces it needs. The code documents
+itself.
+
+**Incorrect (one component, many modes):**
+
+```tsx
+// What does this component actually render?
+<Composer
+  isThread
+  isEditing={false}
+  channelId='abc'
+  showAttachments
+  showFormatting={false}
+/>
+```
+
+**Correct (explicit variants):**
+
+```tsx
+// Immediately clear what this renders
+<ThreadComposer channelId="abc" />
+
+// Or
+<EditMessageComposer messageId="xyz" />
+
+// Or
+<ForwardMessageComposer messageId="123" />
+```
+
+Each implementation is unique, explicit and self-contained. Yet they can each
+use shared parts.
+
+**Implementation:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <ThreadProvider channelId={channelId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <AlsoSendToChannelField channelId={channelId} />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Submit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ThreadProvider>
+  )
+}
+
+function EditMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <EditMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.CancelEdit />
+          <Composer.SaveEdit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </EditMessageProvider>
+  )
+}
+
+function ForwardMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <ForwardMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input placeholder="Add a message, if you'd like." />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Mentions />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ForwardMessageProvider>
+  )
+}
+```
+
+Each variant is explicit about:
+
+- What provider/state it uses
+- What UI elements it includes
+- What actions are available
+
+No boolean prop combinations to reason about. No impossible states.
diff --git a/.claude/skills/composition-patterns/rules/state-lift-state.md b/.claude/skills/composition-patterns/rules/state-lift-state.md
new file mode 100644
index 0000000..d7fe27b
--- /dev/null
+++ b/.claude/skills/composition-patterns/rules/state-lift-state.md
@@ -0,0 +1,125 @@
+---
+title: Lift State into Provider Components
+impact: HIGH
+impactDescription: enables state sharing outside component boundaries
+tags: composition, state, context, providers
+---
+
+## Lift State into Provider Components
+
+Move state management into dedicated provider components. This allows sibling
+components outside the main UI to access and modify state without prop drilling
+or awkward refs.
+
+**Incorrect (state trapped inside component):**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  )
+}
+```
+
+**Incorrect (useEffect to sync state up):**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState('')
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState)
+  useEffect(() => {
+    onInputChange(state.input) // Sync on every change 😬
+  }, [state.input])
+}
+```
+
+**Incorrect (reading state from ref on submit):**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null)
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  )
+}
+```
+
+**Correct (state lifted to provider):**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context)
+  return <Button onPress={actions.submit}>Forward</Button>
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+submit action because it's within the provider. Even though it's a one-off
+component, it can still access the composer's state and actions from outside the
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+nested inside each other—they just need to be within the same provider.
diff --git a/CLAUDE.md b/CLAUDE.md
index c00f64b..95f804e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,7 +13,7 @@ Local-first web app: hand-curated slideshows with automatic, Apple-Memories-grad
 ## Architecture (non-negotiable)
 
 - **Decisions live in pure modules**: Timeline Core (domain + settings cascade), Beat Grid (audio analysis math), Sequence Planner (`(timeline, beatGrid, mediaMetadata) → RenderPlan`). Everything downstream executes the RenderPlan and decides nothing.
-- **Composition (Remotion) and Editor Shell stay thin.** Load the `remotion-best-practices` skill before touching composition/player code.
+- **Composition (Remotion) and Editor Shell stay thin.** Load the `remotion-best-practices` skill before touching composition/player code. Load the `composition-patterns` skill before adding or refactoring `src/editor-shell/` UI.
 - **Determinism**: no wall-clock time or unseeded randomness anywhere the Composition consumes — export depends on it. Variation derives from slide index/seed in the RenderPlan.
 - **Project = folder**: media referenced by filename; all state in `slideshow.json` (schema-versioned) written into the user's folder via the Project Store. No backend, ever.
 - **Settings are a cascade** (global → per-slide). Themes and "Plain mode" are settings data, never special-cased code.
diff --git a/src/editor-shell/App.tsx b/src/editor-shell/App.tsx
index 1261a84..e3e3ef6 100644
--- a/src/editor-shell/App.tsx
+++ b/src/editor-shell/App.tsx
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Player } from '@remotion/player'
-import type { MediaSlide, Slide, TitleSlide } from '../timeline-core/types'
+import type { Slide, TitleSlide } from '../timeline-core/types'
 import { isTitleSlide } from '../timeline-core/types'
 import {
   moveSlide,
@@ -10,7 +10,7 @@ import {
   DEFAULT_GLOBAL_SETTINGS,
   createTitleSlide,
 } from '../timeline-core'
-import type { FitMode, GlobalSettings, SlideOverrides, TransitionType } from '../timeline-core'
+import type { GlobalSettings, SlideOverrides } from '../timeline-core'
 import { enumerateFolder, revokeSlideBlobUrls } from '../project-store/media-loader'
 import {
   openProject,
@@ -20,12 +20,14 @@ import {
   requestHandlePermission,
   type SlideshowJson,
   type RecentProject,
-  SCHEMA_VERSION,
 } from '../project-store'
 import { plan } from '../sequence-planner'
 import { SlideshowComposition } from '../composition'
 import { StoryboardGrid } from './StoryboardGrid'
 import { GlobalSettingsPanel } from './GlobalSettingsPanel'
+import { SlideSettingsDialog } from './SlideSettingsDialog'
+import { TitleSlideDialog } from './TitleSlideDialog'
+import { reconcileSlides, slidesToJson } from './slidePersistence'
 import './App.css'
 
 const FPS = 30
@@ -33,59 +35,6 @@ const COMP_WIDTH = 1920
 const COMP_HEIGHT = 1080
 const AUTOSAVE_DELAY = 2000
 
-function reconcileSlides(enumerated: MediaSlide[], saved: SlideshowJson): Slide[] {
-  const byFilename = new Map(enumerated.map((s) => [s.filename, s]))
-  const ordered: Slide[] = []
-  for (const s of saved.slides) {
-    if (isTitleSlide(s as Slide)) {
-      ordered.push({ ...(s as Slide), excluded: s.excluded ?? false })
-      continue
-    }
-    if (!('filename' in s)) continue
-    const live = byFilename.get(s.filename)
-    if (live) {
-      ordered.push({
-        ...live,
-        durationInFrames: s.durationInFrames,
-        excluded: s.excluded ?? false,
-        overrides: s.overrides,
-      })
-      byFilename.delete(s.filename)
-    }
-  }
-  for (const slide of byFilename.values()) ordered.push(slide)
-  return ordered
-}
-
-function slidesToJson(slides: Slide[], globalSettings: GlobalSettings): SlideshowJson {
-  return {
-    schemaVersion: SCHEMA_VERSION,
-    globalSettings,
-    slides: slides.map(s => {
-      if (isTitleSlide(s)) {
-        return {
-          id: s.id,
-          kind: 'title' as const,
-          heading: s.heading,
-          ...(s.subtext !== undefined ? { subtext: s.subtext } : {}),
-          style: s.style,
-          durationInFrames: s.durationInFrames,
-          excluded: s.excluded,
-          ...(s.overrides && Object.keys(s.overrides).length > 0 ? { overrides: s.overrides } : {}),
-        }
-      }
-      return {
-        id: s.id,
-        filename: s.filename,
-        type: s.type,
-        durationInFrames: s.durationInFrames,
-        excluded: s.excluded,
-        ...(s.overrides && Object.keys(s.overrides).length > 0 ? { overrides: s.overrides } : {}),
-      }
-    }),
-  }
-}
-
 export function App() {
   const [slides, setSlides] = useState<Slide[]>([])
   const [globalSettings, setGlobalSettings] = useState<GlobalSettings>(DEFAULT_GLOBAL_SETTINGS)
@@ -360,253 +309,3 @@ export function App() {
     </div>
   )
 }
-
-function SlideSettingsDialog({
-  slide,
-  globalSettings,
-  onOverride,
-  onClose,
-}: {
-  slide: MediaSlide
-  globalSettings: GlobalSettings
-  onOverride: (id: string, overrides: SlideOverrides | undefined) => void
-  onClose: () => void
-}) {
-  const ov = slide.overrides ?? {}
-  const hasOverrides = Object.keys(ov).length > 0
-
-  function setField<K extends keyof SlideOverrides>(key: K, value: SlideOverrides[K]) {
-    const next = { ...ov, [key]: value }
-    onOverride(slide.id, next)
-  }
-
-  function clearField(key: keyof SlideOverrides) {
-    const next = { ...ov }
-    delete next[key]
-    onOverride(slide.id, Object.keys(next).length > 0 ? next : undefined)
-  }
-
-  function resetAll() {
-    onOverride(slide.id, undefined)
-  }
-
-  return (
-    <div
-      className="slide-dialog-backdrop"
-      onClick={e => { if (e.target === e.currentTarget) onClose() }}
-      role="dialog"
-      aria-modal="true"
-      aria-label={`Settings for ${slide.filename}`}
-    >
-      <div className="slide-dialog">
-        <div className="slide-dialog-header">
-          <h3 className="slide-dialog-title">{slide.filename}</h3>
-          <button className="slide-dialog-close" onClick={onClose} aria-label="Close">×</button>
-        </div>
-
-        {/* Duration — images only */}
-        {slide.type === 'image' && (
-          <div className="override-row">
-            <span className="override-label">Duration</span>
-            <input
-              type="number"
-              className="settings-input"
-              min={1}
-              max={30}
-              step={0.5}
-              value={ov.imageDurationSecs ?? globalSettings.imageDurationSecs}
-              onChange={e => {
-                const v = parseFloat(e.target.value)
-                if (!isNaN(v) && v >= 1 && v <= 30) setField('imageDurationSecs', v)
-              }}
-            />
-            <span className="settings-unit">s</span>
-            {ov.imageDurationSecs !== undefined
-              ? <button className="override-reset" onClick={() => clearField('imageDurationSecs')} title="Reset to global">↩</button>
-              : <span className="override-default">global</span>
-            }
-          </div>
-        )}
-
-        {/* Transition */}
-        <div className="override-row">
-          <span className="override-label">Transition</span>
-          <select
-            className="settings-select"
-            value={ov.transitionType ?? globalSettings.transitionType}
-            onChange={e => setField('transitionType', e.target.value as TransitionType)}
-          >
-            <option value="crossfade">Crossfade</option>
-            <option value="dip-to-black">Dip to black</option>
-            <option value="cut">Cut</option>
-          </select>
-          {ov.transitionType !== undefined
-            ? <button className="override-reset" onClick={() => clearField('transitionType')} title="Reset to global">↩</button>
-            : <span className="override-default">global</span>
-          }
-        </div>
-
-        {/* Ken Burns — images only */}
-        {slide.type === 'image' && (
-          <div className="override-row">
-            <span className="override-label">Ken Burns</span>
-            <input
-              type="checkbox"
-              checked={ov.kenBurns ?? globalSettings.kenBurns}
-              onChange={e => setField('kenBurns', e.target.checked)}
-            />
-            {ov.kenBurns !== undefined
-              ? <button className="override-reset" onClick={() => clearField('kenBurns')} title="Reset to global">↩</button>
-              : <span className="override-default">global</span>
-            }
-          </div>
-        )}
-
-        {/* Fit mode — images only */}
-        {slide.type === 'image' && (
-          <div className="override-row">
-            <span className="override-label">Fit mode</span>
-            <select
-              className="settings-select"
-              value={ov.fitMode ?? globalSettings.fitMode}
-              onChange={e => setField('fitMode', e.target.value as FitMode)}
-            >
-              <option value="cover">Cover (crop)</option>
-              <option value="contain">Letterbox</option>
-              <option value="blur-fill">Blur fill</option>
-            </select>
-            {ov.fitMode !== undefined
-              ? <button className="override-reset" onClick={() => clearField('fitMode')} title="Reset to global">↩</button>
-              : <span className="override-default">global</span>
-            }
-          </div>
-        )}
-
-        <div className="slide-dialog-footer">
-          {hasOverrides && (
-            <button className="override-reset-all" onClick={resetAll}>
-              Reset all to global defaults
-            </button>
-          )}
-        </div>
-      </div>
-    </div>
-  )
-}
-
-function TitleSlideDialog({
-  slide,
-  onUpdate,
-  onOverride,
-  onClose,
-}: {
-  slide: TitleSlide
-  onUpdate: (id: string, updates: Partial<Pick<TitleSlide, 'heading' | 'subtext' | 'style' | 'durationInFrames'>>) => void
-  onOverride: (id: string, overrides: SlideOverrides | undefined) => void
-  onClose: () => void
-}) {
-  const ov = slide.overrides ?? {}
-
-  function setTransition(type: TransitionType) {
-    onOverride(slide.id, { ...ov, transitionType: type })
-  }
-
-  function clearTransition() {
-    const next = { ...ov }
-    delete next.transitionType
-    onOverride(slide.id, Object.keys(next).length > 0 ? next : undefined)
-  }
-
-  return (
-    <div
-      className="slide-dialog-backdrop"
-      onClick={e => { if (e.target === e.currentTarget) onClose() }}
-      role="dialog"
-      aria-modal="true"
-      aria-label="Title slide settings"
-    >
-      <div className="slide-dialog">
-        <div className="slide-dialog-header">
-          <h3 className="slide-dialog-title">Title Slide</h3>
-          <button className="slide-dialog-close" onClick={onClose} aria-label="Close">×</button>
-        </div>
-
-        <div className="override-row">
-          <span className="override-label">Heading</span>
-          <input
-            type="text"
-            className="settings-input"
-            value={slide.heading}
-            onChange={e => onUpdate(slide.id, { heading: e.target.value })}
-            placeholder="Enter heading"
-            style={{ flex: 1 }}
-          />
-        </div>
-
-        <div className="override-row">
-          <span className="override-label">Subtext</span>
-          <input
-            type="text"
-            className="settings-input"
-            value={slide.subtext ?? ''}
-            onChange={e => onUpdate(slide.id, { subtext: e.target.value || undefined })}
-            placeholder="Optional subtext"
-            style={{ flex: 1 }}
-          />
-        </div>
-
-        <div className="override-row">
-          <span className="override-label">Style</span>
-          <select
-            className="settings-select"
-            value={slide.style}
-            onChange={e => onUpdate(slide.id, { style: e.target.value as 'light' | 'dark' })}
-          >
-            <option value="dark">Dark</option>
-            <option value="light">Light</option>
-          </select>
-        </div>
-
-        <div className="override-row">
-          <span className="override-label">Duration</span>
-          <input
-            type="number"
-            className="settings-input"
-            min={1}
-            max={30}
-            step={0.5}
-            value={slide.durationInFrames / FPS}
-            onChange={e => {
-              const v = parseFloat(e.target.value)
-              if (!isNaN(v) && v >= 1 && v <= 30) onUpdate(slide.id, { durationInFrames: Math.round(v * FPS) })
-            }}
-          />
-          <span className="settings-unit">s</span>
-        </div>
-
-        <div className="override-row">
-          <span className="override-label">Transition</span>
-          <select
-            className="settings-select"
-            value={ov.transitionType ?? 'global'}
-            onChange={e => {
-              const v = e.target.value
-              if (v === 'global') clearTransition()
-              else setTransition(v as TransitionType)
-            }}
-          >
-            <option value="global">Global default</option>
-            <option value="crossfade">Crossfade</option>
-            <option value="dip-to-black">Dip to black</option>
-            <option value="cut">Cut</option>
-          </select>
-          {ov.transitionType !== undefined && (
-            <button className="override-reset" onClick={clearTransition} title="Reset to global">↩</button>
-          )}
-        </div>
-
-        <div className="slide-dialog-footer" />
-      </div>
-    </div>
-  )
-}
diff --git a/src/editor-shell/SlideSettingsDialog.tsx b/src/editor-shell/SlideSettingsDialog.tsx
new file mode 100644
index 0000000..dbe8f5d
--- /dev/null
+++ b/src/editor-shell/SlideSettingsDialog.tsx
@@ -0,0 +1,128 @@
+import type { MediaSlide } from '../timeline-core/types'
+import type { FitMode, GlobalSettings, SlideOverrides, TransitionType } from '../timeline-core'
+
+type Props = {
+  globalSettings: GlobalSettings
+  onClose: () => void
+  onOverride: (id: string, overrides: SlideOverrides | undefined) => void
+  slide: MediaSlide
+}
+
+export function SlideSettingsDialog({ globalSettings, onClose, onOverride, slide }: Props) {
+  const ov = slide.overrides ?? {}
+  const hasOverrides = Object.keys(ov).length > 0
+
+  function setField<K extends keyof SlideOverrides>(key: K, value: SlideOverrides[K]) {
+    const next = { ...ov, [key]: value }
+    onOverride(slide.id, next)
+  }
+
+  function clearField(key: keyof SlideOverrides) {
+    const next = { ...ov }
+    delete next[key]
+    onOverride(slide.id, Object.keys(next).length > 0 ? next : undefined)
+  }
+
+  function resetAll() {
+    onOverride(slide.id, undefined)
+  }
+
+  return (
+    <div
+      className="slide-dialog-backdrop"
+      onClick={e => { if (e.target === e.currentTarget) onClose() }}
+      role="dialog"
+      aria-modal="true"
+      aria-label={`Settings for ${slide.filename}`}
+    >
+      <div className="slide-dialog">
+        <div className="slide-dialog-header">
+          <h3 className="slide-dialog-title">{slide.filename}</h3>
+          <button className="slide-dialog-close" onClick={onClose} aria-label="Close">×</button>
+        </div>
+
+        {slide.type === 'image' ? (
+          <div className="override-row">
+            <span className="override-label">Duration</span>
+            <input
+              type="number"
+              className="settings-input"
+              min={1}
+              max={30}
+              step={0.5}
+              value={ov.imageDurationSecs ?? globalSettings.imageDurationSecs}
+              onChange={e => {
+                const v = parseFloat(e.target.value)
+                if (!isNaN(v) && v >= 1 && v <= 30) setField('imageDurationSecs', v)
+              }}
+            />
+            <span className="settings-unit">s</span>
+            {ov.imageDurationSecs !== undefined
+              ? <button className="override-reset" onClick={() => clearField('imageDurationSecs')} title="Reset to global">↩</button>
+              : <span className="override-default">global</span>
+            }
+          </div>
+        ) : null}
+
+        <div className="override-row">
+          <span className="override-label">Transition</span>
+          <select
+            className="settings-select"
+            value={ov.transitionType ?? globalSettings.transitionType}
+            onChange={e => setField('transitionType', e.target.value as TransitionType)}
+          >
+            <option value="crossfade">Crossfade</option>
+            <option value="dip-to-black">Dip to black</option>
+            <option value="cut">Cut</option>
+          </select>
+          {ov.transitionType !== undefined
+            ? <button className="override-reset" onClick={() => clearField('transitionType')} title="Reset to global">↩</button>
+            : <span className="override-default">global</span>
+          }
+        </div>
+
+        {slide.type === 'image' ? (
+          <div className="override-row">
+            <span className="override-label">Ken Burns</span>
+            <input
+              type="checkbox"
+              checked={ov.kenBurns ?? globalSettings.kenBurns}
+              onChange={e => setField('kenBurns', e.target.checked)}
+            />
+            {ov.kenBurns !== undefined
+              ? <button className="override-reset" onClick={() => clearField('kenBurns')} title="Reset to global">↩</button>
+              : <span className="override-default">global</span>
+            }
+          </div>
+        ) : null}
+
+        {slide.type === 'image' ? (
+          <div className="override-row">
+            <span className="override-label">Fit mode</span>
+            <select
+              className="settings-select"
+              value={ov.fitMode ?? globalSettings.fitMode}
+              onChange={e => setField('fitMode', e.target.value as FitMode)}
+            >
+              <option value="cover">Cover (crop)</option>
+              <option value="contain">Letterbox</option>
+              <option value="blur-fill">Blur fill</option>
+            </select>
+            {ov.fitMode !== undefined
+              ? <button className="override-reset" onClick={() => clearField('fitMode')} title="Reset to global">↩</button>
+              : <span className="override-default">global</span>
+            }
+          </div>
+        ) : null}
+
+        <div className="slide-dialog-footer">
+          {hasOverrides ? (
+            <button className="override-reset-all" onClick={resetAll}>
+              Reset all to global defaults
+            </button>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/editor-shell/TitleSlideDialog.tsx b/src/editor-shell/TitleSlideDialog.tsx
new file mode 100644
index 0000000..878f4a3
--- /dev/null
+++ b/src/editor-shell/TitleSlideDialog.tsx
@@ -0,0 +1,118 @@
+import type { TitleSlide } from '../timeline-core/types'
+import type { SlideOverrides, TransitionType } from '../timeline-core'
+
+const FPS = 30
+
+type Props = {
+  onClose: () => void
+  onOverride: (id: string, overrides: SlideOverrides | undefined) => void
+  onUpdate: (id: string, updates: Partial<Pick<TitleSlide, 'heading' | 'subtext' | 'style' | 'durationInFrames'>>) => void
+  slide: TitleSlide
+}
+
+export function TitleSlideDialog({ onClose, onOverride, onUpdate, slide }: Props) {
+  const ov = slide.overrides ?? {}
+
+  function setTransition(type: TransitionType) {
+    onOverride(slide.id, { ...ov, transitionType: type })
+  }
+
+  function clearTransition() {
+    const next = { ...ov }
+    delete next.transitionType
+    onOverride(slide.id, Object.keys(next).length > 0 ? next : undefined)
+  }
+
+  return (
+    <div
+      className="slide-dialog-backdrop"
+      onClick={e => { if (e.target === e.currentTarget) onClose() }}
+      role="dialog"
+      aria-modal="true"
+      aria-label="Title slide settings"
+    >
+      <div className="slide-dialog">
+        <div className="slide-dialog-header">
+          <h3 className="slide-dialog-title">Title Slide</h3>
+          <button className="slide-dialog-close" onClick={onClose} aria-label="Close">×</button>
+        </div>
+
+        <div className="override-row">
+          <span className="override-label">Heading</span>
+          <input
+            type="text"
+            className="settings-input"
+            value={slide.heading}
+            onChange={e => onUpdate(slide.id, { heading: e.target.value })}
+            placeholder="Enter heading"
+            style={{ flex: 1 }}
+          />
+        </div>
+
+        <div className="override-row">
+          <span className="override-label">Subtext</span>
+          <input
+            type="text"
+            className="settings-input"
+            value={slide.subtext ?? ''}
+            onChange={e => onUpdate(slide.id, { subtext: e.target.value || undefined })}
+            placeholder="Optional subtext"
+            style={{ flex: 1 }}
+          />
+        </div>
+
+        <div className="override-row">
+          <span className="override-label">Style</span>
+          <select
+            className="settings-select"
+            value={slide.style}
+            onChange={e => onUpdate(slide.id, { style: e.target.value as 'light' | 'dark' })}
+          >
+            <option value="dark">Dark</option>
+            <option value="light">Light</option>
+          </select>
+        </div>
+
+        <div className="override-row">
+          <span className="override-label">Duration</span>
+          <input
+            type="number"
+            className="settings-input"
+            min={1}
+            max={30}
+            step={0.5}
+            value={slide.durationInFrames / FPS}
+            onChange={e => {
+              const v = parseFloat(e.target.value)
+              if (!isNaN(v) && v >= 1 && v <= 30) onUpdate(slide.id, { durationInFrames: Math.round(v * FPS) })
+            }}
+          />
+          <span className="settings-unit">s</span>
+        </div>
+
+        <div className="override-row">
+          <span className="override-label">Transition</span>
+          <select
+            className="settings-select"
+            value={ov.transitionType ?? 'global'}
+            onChange={e => {
+              const v = e.target.value
+              if (v === 'global') clearTransition()
+              else setTransition(v as TransitionType)
+            }}
+          >
+            <option value="global">Global default</option>
+            <option value="crossfade">Crossfade</option>
+            <option value="dip-to-black">Dip to black</option>
+            <option value="cut">Cut</option>
+          </select>
+          {ov.transitionType !== undefined ? (
+            <button className="override-reset" onClick={clearTransition} title="Reset to global">↩</button>
+          ) : null}
+        </div>
+
+        <div className="slide-dialog-footer" />
+      </div>
+    </div>
+  )
+}
diff --git a/src/editor-shell/slidePersistence.ts b/src/editor-shell/slidePersistence.ts
new file mode 100644
index 0000000..a10b03c
--- /dev/null
+++ b/src/editor-shell/slidePersistence.ts
@@ -0,0 +1,57 @@
+import type { MediaSlide, Slide } from '../timeline-core/types'
+import { isTitleSlide } from '../timeline-core/types'
+import type { GlobalSettings } from '../timeline-core'
+import { SCHEMA_VERSION, type SlideshowJson } from '../project-store'
+
+export function reconcileSlides(enumerated: MediaSlide[], saved: SlideshowJson): Slide[] {
+  const byFilename = new Map(enumerated.map((slide) => [slide.filename, slide]))
+  const ordered: Slide[] = []
+  for (const savedSlide of saved.slides) {
+    if (isTitleSlide(savedSlide as Slide)) {
+      ordered.push({ ...(savedSlide as Slide), excluded: savedSlide.excluded ?? false })
+      continue
+    }
+    if (!('filename' in savedSlide)) continue
+    const live = byFilename.get(savedSlide.filename)
+    if (live) {
+      ordered.push({
+        ...live,
+        durationInFrames: savedSlide.durationInFrames,
+        excluded: savedSlide.excluded ?? false,
+        overrides: savedSlide.overrides,
+      })
+      byFilename.delete(savedSlide.filename)
+    }
+  }
+  for (const slide of byFilename.values()) ordered.push(slide)
+  return ordered
+}
+
+export function slidesToJson(slides: Slide[], globalSettings: GlobalSettings): SlideshowJson {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    globalSettings,
+    slides: slides.map(slide => {
+      if (isTitleSlide(slide)) {
+        return {
+          id: slide.id,
+          kind: 'title' as const,
+          heading: slide.heading,
+          ...(slide.subtext !== undefined ? { subtext: slide.subtext } : {}),
+          style: slide.style,
+          durationInFrames: slide.durationInFrames,
+          excluded: slide.excluded,
+          ...(slide.overrides && Object.keys(slide.overrides).length > 0 ? { overrides: slide.overrides } : {}),
+        }
+      }
+      return {
+        id: slide.id,
+        filename: slide.filename,
+        type: slide.type,
+        durationInFrames: slide.durationInFrames,
+        excluded: slide.excluded,
+        ...(slide.overrides && Object.keys(slide.overrides).length > 0 ? { overrides: slide.overrides } : {}),
+      }
+    }),
+  }
+}

From 07d3a159ee1bd4ddb3a6dc65d32ce17af1f44a4f Mon Sep 17 00:00:00 2001
From: cbaucom <chrisrb83@gmail.com>
Date: Wed, 10 Jun 2026 22:30:06 -0400
Subject: [PATCH 2/2] docs: add project-specific standards/slideshow.md

Replace broken references to generic cross-repo standards templates
with a single slideshow-focused doc. Point CLAUDE.md, composition-patterns,
and code-reviewer at it.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .claude/agents/code-reviewer.md              |   2 +-
 .claude/skills/composition-patterns/SKILL.md |   2 +-
 CLAUDE.md                                    |   9 +-
 standards/slideshow.md                       | 104 +++++++++++++++++++
 4 files changed, 107 insertions(+), 10 deletions(-)
 create mode 100644 standards/slideshow.md

diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md
index 2bced5e..69f9d6e 100644
--- a/.claude/agents/code-reviewer.md
+++ b/.claude/agents/code-reviewer.md
@@ -6,7 +6,7 @@ Principal reviewer only — identify issues; do not implement fixes. Adapted fro
 
 1. Git diff for the branch (`git diff main...HEAD`)
 2. The GitHub issue being implemented (acceptance criteria are the spec)
-3. Standards: `CLAUDE.md` (architecture invariants) and the parent PRD (issue #1, Implementation & Testing Decisions)
+3. Standards: `CLAUDE.md`, `standards/slideshow.md`, and the parent PRD (issue #1, Implementation & Testing Decisions)
 
 ## Lenses
 
diff --git a/.claude/skills/composition-patterns/SKILL.md b/.claude/skills/composition-patterns/SKILL.md
index 7c83494..87c323b 100644
--- a/.claude/skills/composition-patterns/SKILL.md
+++ b/.claude/skills/composition-patterns/SKILL.md
@@ -8,7 +8,7 @@ metadata:
 
 ## When to use
 
-Load this skill before adding or refactoring UI in `src/editor-shell/`. Read `standards/react.md` and `standards/architecture.md` alongside these rules.
+Load this skill before adding or refactoring UI in `src/editor-shell/`. Read `standards/slideshow.md` alongside these rules.
 
 Triggers:
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 95f804e..e025c36 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,11 +24,4 @@ Vite + React + TypeScript, `@remotion/player`, Web Audio API, File System Access
 
 ## Code standards
 
-Project-wide rules live in `standards/` — read the relevant file before writing code in that domain:
-
-- `standards/architecture.md` — TypeScript strictness, module boundaries, naming, file size limits
-- `standards/testing.md` — TDD workflow, coverage floors, what to test
-- `standards/react.md` — component rules, state hierarchy, anti-patterns
-- `standards/security.md` — secrets, input validation, dependency policy
-
-Key rules that apply here: no `any`, explicit return types on all exported functions, no magic numbers (use named constants), files ≤ 300 lines (split when you exceed this).
+Read `standards/slideshow.md` before writing code — module boundaries, TypeScript, React SPA patterns, testing policy, and security for this repo. Pure-module TDD workflow: `.claude/skills/tdd/`.
diff --git a/standards/slideshow.md b/standards/slideshow.md
new file mode 100644
index 0000000..c3052f6
--- /dev/null
+++ b/standards/slideshow.md
@@ -0,0 +1,104 @@
+# Slideshow Maker — Code Standards
+
+> Project-specific rules for agents and humans. Read alongside `CLAUDE.md` and the PRD (issue #1).
+
+---
+
+## Module map
+
+```
+src/timeline-core/     — pure domain: slides, settings cascade, ordering
+src/beat-grid/         — (future) BPM detection + nudge math
+src/sequence-planner/  — (timeline, beatGrid, metadata) → RenderPlan
+src/project-store/     — File System Access API, slideshow.json, autosave
+src/composition/       — thin Remotion layer, executes RenderPlan only
+src/editor-shell/      — storyboard, settings panels, player host
+```
+
+**Boundaries:**
+
+- Pure modules own decisions (timing, beats, fit, cascade). Composition and Editor Shell execute plans and glue UI — they do not re-derive slideshow logic.
+- No circular dependencies across modules.
+
+---
+
+## TypeScript
+
+- `strict` always. No `any` — use `unknown` and narrow.
+- Prefer type inference; add explicit return types only when inference fails or the linter requires it.
+- Named exports only (no default exports).
+- No enums — use `as const` objects and derived union types.
+- No magic numbers or strings — named constants at module top.
+
+---
+
+## File and function size
+
+- Files ≤ 300 lines — split when exceeded (e.g. dedicated dialog components, `slidePersistence.ts`).
+- Functions ≤ 40 lines when practical — extract helpers.
+
+---
+
+## React (Vite SPA)
+
+- One component per file in `editor-shell/` and `composition/`.
+- Props type in the same file (`type Props = { ... }`).
+- Styles in colocated `.css` files — not Tailwind.
+- App-level state with callback props is fine at current scale; lift to providers when siblings outside a subtree need the same state (see `composition-patterns` skill).
+- Explicit variant components over boolean props (`TitleSlideDialog` / `SlideSettingsDialog`, not one dialog with `isTitle`).
+- Modals: `role="dialog"`, `aria-modal`, labelled controls.
+
+**Skills for UI work:**
+
+- `src/composition/` or player → `remotion-best-practices`
+- `src/editor-shell/` refactors → `composition-patterns`
+
+---
+
+## Testing
+
+Follow `.claude/skills/tdd/` for pure-module work (red → green → refactor on acceptance criteria).
+
+| Layer | Unit tests? | Notes |
+| --- | --- | --- |
+| Timeline Core, Beat Grid, Sequence Planner | Yes | Table, golden, property tests; colocated `*.test.ts` |
+| Project Store, Jamendo client | Yes | In-memory FS fakes; mocked HTTP — no live network |
+| Composition, Editor Shell | No | UI slices: `playwright-cli` smoke; correctness flows from RenderPlan tests |
+
+- Test through public interfaces only.
+- `pnpm test`, `pnpm build`, and `pnpm lint` must pass before merge.
+
+---
+
+## Determinism (Composition)
+
+- No `Date.now()`, `performance.now()`, or unseeded `Math.random()` in anything the Composition renders.
+- Motion, transitions, and variation derive from RenderPlan indices and seeds.
+
+---
+
+## Security and config
+
+- No secrets in the repo. Jamendo `client_id` via environment (`.env.local`; document in `.env.example` when wired).
+- Treat folder contents as untrusted input — validate filenames and paths at boundaries.
+- Chromium-only (File System Access API). No pretend cross-browser FS support.
+
+---
+
+## Naming
+
+| Thing | Convention | Example |
+| --- | --- | --- |
+| Component files | PascalCase | `StoryboardGrid.tsx` |
+| Helper modules | camelCase or domain name | `slidePersistence.ts` |
+| Event handlers | `handle` prefix | `handleSlideClick` |
+| Type guards / booleans | `is` / `has` prefix | `isTitleSlide` |
+
+---
+
+## Do not
+
+- Special-case themes or Plain mode in code — they are settings data in the cascade.
+- Re-decide timing, fit, or transitions in Composition or Editor Shell.
+- Introduce Next.js, RSC, TanStack Query, or server-side patterns — client-only Vite SPA.
+- Add a backend, accounts, or cloud sync — project = folder on disk.