uifolio 0.3.0 → 0.4.0

package/cli/uifolio.mjs

@@ -7,6 +7,7 @@
  *   uifolio list                          liste des composants disponibles
  *   uifolio init [--cwd dir]              écrit uifolio.json (config cible)
  *   uifolio add <noms...> [options]       copie les composants + helpers
+ *                                        --page <chemin>  crée ou adapte la page cible
  *
  * Options :
  *   --cwd <dir>          projet cible (défaut : répertoire courant)
@@ -16,11 +17,14 @@
  *   --color <hex>        intègre cette couleur aux fichiers copiés (plus de --primary)
  *   --radius <px>        écrit --radius dans uifolio-theme.css
  *   --force              écrase les fichiers existants
+ *   --page <chemin>      chemin de la page (ex : src/pages/calendar.tsx)
+ *                        crée la page si elle n'existe pas, sinon y ajoute
+ *                        l'import et un appel de composant
  *   --dry-run            affiche ce qui serait copié sans rien écrire
  *
  * Exemples :
  *   node cli/uifolio.mjs add calendar otp --cwd ../mon-projet
- *   node cli/uifolio.mjs add calendar --color "#10B981"
+ *   node cli/uifolio.mjs add calendar --color "#10B981" --page src/pages/calendar.tsx
  *   node cli/uifolio.mjs add video-player --alias "#lib" --dry-run
  */
 
@@ -120,6 +124,96 @@ function externalDeps(source) {
   return [...deps]
 }
 
+/**
+ * Liste les pages cx (fichiers .tsx dans src/pages/) du projet cible.
+ */
+function listPagesInCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return []
+  try {
+    const cwdPath = resolve(cwd)
+    const srcRoot = join(cwdPath, 'src')
+    if (!existsSync(srcRoot)) return []
+    const pagesDir = join(srcRoot, 'pages')
+    if (!existsSync(pagesDir)) return []
+    const entries = readdirSync(pagesDir)
+    if (!Array.isArray(entries)) return []
+    return entries
+      .filter((name) => typeof name === 'string' && name.endsWith('.tsx'))
+      .map((name) => join('src', 'pages', name))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Demande interactivement à l'utilisateur quelle page utiliser, ou retourne
+ * null si l'entrée n'est pas valide / la saisie est vide.
+ */
+function choosePageInteraction(pages, cwd) {
+  if (!Array.isArray(pages) || pages.length === 0) return null
+  if (pages.length === 1) {
+    info(`Une page existe déjà : ${pages[0]} (utilisée par défaut)`)
+    try {
+      return join(resolve(cwd), pages[0])
+    } catch {
+      return null
+    }
+  }
+  let cwdPath = cwd
+  try {
+    cwdPath = resolve(cwd)
+  } catch {
+    cwdPath = process.cwd()
+  }
+
+  console.log('\nPlusieurs pages existent dans src/pages/. Choisis celle où importer le/des composant(s) :')
+  pages.forEach((p, index) => {
+    console.log(`  ${index + 1}. ${p}`)
+  })
+  console.log('  0. Ne pas importer dans une page')
+
+  const answer = promptPageChoice()
+  if (answer === null) {
+    info('Aucune page sélectionnée : les composants seront copiés sans être importés dans une page.')
+    return null
+  }
+  if (answer === 0) {
+    info('Import dans une page annulé.')
+    return null
+  }
+  const selected = pages[answer - 1]
+  if (!selected) {
+    info('Choix invalide : aucune page sélectionnée.')
+    return null
+  }
+  info(`Page retenue : ${selected}`)
+  try {
+    return join(cwdPath, selected)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Lecture synchrone d'une ligne depuis stdin (pour l'interaction CLI).
+ * Retourne null en cas d'erreur de lecture ou d'EOF.
+ */
+function promptPageChoice() {
+  const chunk = Buffer.alloc(1024)
+  try {
+    const n = process.stdin.read(0, chunk.length, chunk)
+    if (n <= 0) return null
+    const text = chunk.toString('utf8', 0, n).trim()
+    if (text === '') return null
+    const parsed = Number(text)
+    if (!Number.isInteger(parsed)) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
 /**
  * Résolution transitive : un composant importe des helpers (@/lib/…)
  * qui peuvent eux-mêmes importer d'autres fichiers locaux.
@@ -275,12 +369,28 @@ function commandInit({ flags }) {
   info('Puis : uifolio add video-player calendar …')
 }
 
+
 function commandAdd({ positional, flags }) {
   const names = positional.map((name) => ALIASES[name] ?? name)
+
   if (names.length === 0) fail('Aucun composant demandé. Ex. : uifolio add calendar otp')
 
   const cwd = resolve(flags.cwd ?? process.cwd())
   const config = readConfig(cwd) ?? {}
+  const pageFlag = typeof flags.page === 'string' ? flags.page : undefined
+  let pageTarget = pageFlag ? resolve(cwd, pageFlag) : null
+
+  // Détermine la page cible effective : --page explicite, choix interactif, ou aucune.
+  if (!pageTarget) {
+    const pages = listPagesInCwd(cwd)
+    if (pages.length > 0) {
+      const chosen = choosePageInteraction(pages, cwd)
+      if (chosen) pageTarget = chosen
+    }
+  }
+
+  const createPage = Boolean(pageTarget) && !existsSync(pageTarget)
+  let pageImports = []
 
   const componentsDir = typeof flags.dir === 'string' ? flags.dir : config.dir ?? 'src/components/ui'
   const libDir = typeof flags.lib === 'string' ? flags.lib : config.lib ?? 'src/lib'
@@ -300,11 +410,26 @@ function commandAdd({ positional, flags }) {
   }
 
   if (!dryRun && !existsSync(cwd)) fail(`Répertoire cible introuvable : ${cwd}`)
+  if (pageTarget && !existsSync(pageTarget) && !dryRun) {
+    const bad = pageFlag ?? relative(cwd, pageTarget)
+    fail(`Page cible introuvable : ${bad}.`)
+  }
+  if (pageTarget && !existsSync(pageTarget) && dryRun) {
+    info(`[dry-run] page cible introuvable : ${pageFlag ?? relative(cwd, pageTarget)} (simulation uniquement).`)
+    pageTarget = null
+  }
 
   const deps = new Set(LIB_DEPS)
   const written = new Set()
   const skipped = []
 
+  // Prépare les imports qui seront injectés dans la page cible.
+  for (const name of names) {
+    if (!pageTarget) continue
+    const importPath = relative(cwd, join(componentsDir, `${name}.tsx`))
+    pageImports.push({ name, importPath })
+  }
+
   for (const name of names) {
     const entry = join(REGISTRY_UI, `${name}.tsx`)
     const files = collectFiles(entry, REGISTRY_SRC)
@@ -358,6 +483,45 @@ function commandAdd({ positional, flags }) {
       info(`Pense à aligner l'alias ${targetAlias} dans ton tsconfig/vite (remplace de @/).`)
     }
     console.log('')
+  }  // Crée ou adapte la page cible si une page cible a été sélectionnée.
+  if (pageTarget) {
+    const dir = dirname(pageTarget)
+    if (createPage) {
+      if (!dryRun) {
+        mkdirSync(dir, { recursive: true })
+        writeFileSync(
+          pageTarget,
+          `import { ${pageImports.map((p) => p.name).join(', ')} } from '${relative(dir, join(cwd, componentsDir)).replace(/\\/g, '/')}'\n'\n` +
+            `export default function Page() {\n` +
+            `  return (<>\n` +
+            pageImports.map((p) => `    <${p.name} />`).join('\n') +
+            `\n  </>)\n` +
+            `}\n`,
+          'utf8',
+        )
+      }
+      ok(`${dryRun ? '[dry-run] ' : ''}Page créée : ${relative(cwd, pageTarget)}`)
+      for (const p of pageImports) {
+        info(`· <${p.name} /> importé depuis ${relative(cwd, join(componentsDir, `${p.name}.tsx`))}`)
+      }
+    } else {
+      if (dryRun) {
+        info(`[dry-run] page existante détectée : ${relative(cwd, pageTarget)}`)
+      } else {
+        const source = readFileSync(pageTarget, 'utf8')
+        const rendered =
+          pageImports.map((p) => `import { ${p.name} } from '${relative(dirname(pageTarget), join(cwd, componentsDir)).replace(/\\/g, '/')}';`).join('\n')
+        const functionPoint = source.indexOf('function ')
+        const insertPoint =
+          functionPoint !== -1 ? functionPoint : source.lastIndexOf('</')
+        const updatedSource =
+          insertPoint === -1
+            ? source + '\n' + rendered + '\n' + pageImports.map((p) => `<${p.name} />`).join('\n')
+            : source.slice(0, insertPoint) + '\n' + rendered + '\n' + source.slice(insertPoint)
+        writeFileSync(pageTarget, updatedSource, 'utf8')
+      }
+      ok(`Page existante mise à jour : ${relative(cwd, pageTarget)}`)
+    }
   }
 }
 
@@ -382,17 +546,37 @@ Options :
   --radius <px>     arrondi global (0–24) dans uifolio-theme.css
   --force           écrase les fichiers existants
   --dry-run         simule sans écrire
+  --page <chemin>   page cible (ex : src/pages/calendar.tsx). Avec --page, la CLI crée la page
+                    si elle n'existe pas, ou y ajoute l'import + l'appel du/des composant(s).
+                    Sans --page et quand des pages existent déjà dans src/pages, la CLI demande
+                    interactivement laquelle utiliser avant d'importer.
 
 Exemples :
   node cli/uifolio.mjs add video-player calendar otp --cwd ../mon-projet
   node cli/uifolio.mjs add otp --color "#10B981" --radius 8
   node cli/uifolio.mjs add otp --alias "#lib" --dry-run
+  node cli/uifolio.mjs add calendar --page src/pages/calendar.tsx
 `)
 }
 
 const { positional, flags } = parseArgs(process.argv.slice(2))
 const command = positional.shift()
 
+// Requête interactive de la page cible avant toute écriture, sauf si --page est déjà passé.
+if (command === 'add' && typeof flags.page !== 'string') {
+  let cwd
+  try {
+    cwd = resolve(flags.cwd ?? process.cwd())
+  } catch {
+    cwd = process.cwd()
+  }
+  const pages = listPagesInCwd(cwd)
+  if (pages.length > 0) {
+    const target = choosePageInteraction(pages, cwd)
+    if (target) flags.page = target
+  }
+}
+
 switch (command) {
   case 'list':
     commandList()

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "uifolio",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI qui copie des composants React (calendrier, lecteurs vidéo/audio, OTP, éditeur, upload) et leurs helpers dans ton projet, avec des tokens Tailwind CSS 4.",
   "type": "module",
   "license": "MIT",
   "author": "Barronakn <jeanbarronalokpon@gmail.com>",
-  "homepage": "https://github.com/Barronakn/UIfolio#readme",
+  "homepage": "https://ui.folio.barrondev.site",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Barronakn/UIfolio.git"
@@ -14,17 +14,32 @@
     "url": "https://github.com/Barronakn/UIfolio/issues"
   },
   "keywords": [
-    "uifolio",
     "react",
-    "components",
-    "ui",
-    "cli",
-    "tailwind",
+    "react-component",
     "tailwindcss",
+    "ui-components",
+    "component-library",
+    "cli",
+    "uifolio",
     "calendar",
     "video-player",
+    "audio-player",
     "otp",
-    "shadcn"
+    "color-picker",
+    "file-upload",
+    "rich-text-editor",
+    "command-menu",
+    "resizable-panels",
+    "time-picker",
+    "cadence",
+    "storytelling",
+    "accordion",
+    "text-reveal",
+    "hls.js",
+    "vtt",
+    "shadcn",
+    "shadcn-clone",
+    "shadcn-like"
   ],
   "engines": {
     "node": ">=18"
@@ -41,6 +56,7 @@
     "src/lib/color.ts",
     "src/lib/date.ts",
     "src/lib/uploader.ts",
+    "src/lib/use-controllable.ts",
     "src/lib/use-hotkeys.ts",
     "src/lib/use-reduced-motion.ts",
     "src/lib/use-theme.ts",

package/src/components/ui/icon-picker.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { Search, X, Check, ChevronDown } from 'lucide-react'
 import { cn } from '@/lib/utils'
 
@@ -155,20 +155,25 @@ export function IconGlyph({
   className?: string
 }) {
   const [data, setData] = useState<IconData | null>(() => iconCache.get(icon) ?? null)
+  const [prevIcon, setPrevIcon] = useState(icon)
+  const loadRef = useRef<Promise<void> | null>(null)
+
+  // Ajustement pendant le rendu : une icône déjà en cache s'applique sans effet.
+  if (prevIcon !== icon) {
+    setPrevIcon(icon)
+    setData(iconCache.get(icon) ?? null)
+  }
 
   useEffect(() => {
-    const cached = iconCache.get(icon)
-    if (cached) {
-      setData(cached)
-      return
-    }
-    let cancelled = false
-    setData(null)
-    loadIcons([icon]).then((icons) => {
-      if (!cancelled) setData(icons[icon] ?? null)
+    if (iconCache.get(icon)) return
+    const current = loadIcons([icon]).then((icons) => {
+      if (loadRef.current === current) {
+        setData(icons[icon] ?? null)
+      }
     })
+    loadRef.current = current
     return () => {
-      cancelled = true
+      loadRef.current = null
     }
   }, [icon])
 
@@ -187,6 +192,7 @@ export function IconPicker({
   const [icons, setIcons] = useState<string[]>([])
   const [bodies, setBodies] = useState<Record<string, IconData>>({})
   const [loading, setLoading] = useState(false)
+  const loadingRef = useRef<Promise<void> | null>(null)
 
   useEffect(() => {
     if (!open) return
@@ -221,12 +227,14 @@ export function IconPicker({
 
   useEffect(() => {
     if (icons.length === 0) return
-    let cancelled = false
-    loadIcons(icons).then((loaded) => {
-      if (!cancelled) setBodies((prev) => ({ ...prev, ...loaded }))
+    const current = loadIcons(icons).then((loaded) => {
+      if (loadingRef.current === current) {
+        setBodies((prev) => ({ ...prev, ...loaded }))
+      }
     })
+    loadingRef.current = current
     return () => {
-      cancelled = true
+      loadingRef.current = null
     }
   }, [icons])
 

package/src/components/ui/otp-input.tsx

@@ -42,11 +42,10 @@ export function OtpInput({
 }: OtpInputProps) {
   const [internalValue, setInternalValue] = useState(defaultValue)
   const current = value ?? internalValue
-  const [phase, setPhase] = useState<'idle' | 'success'>('idle')
+  const complete = current.length === length && /^\d+$/.test(current)
+  const phase = complete && !error ? 'success' : 'idle'
 
   const inputs = useRef<Array<HTMLInputElement | null>>([])
-  const completed = useRef(false)
-  const completedValue = useRef<string | null>(null)
   const onChangeRef = useRef(onChange)
   const onCompleteRef = useRef(onComplete)
 
@@ -55,39 +54,16 @@ export function OtpInput({
     onCompleteRef.current = onComplete
   })
 
+  useEffect(() => {
+    if (autoFocus) inputs.current[0]?.focus()
+  }, [autoFocus])
+
   const commit = (next: string) => {
     const cleaned = next.replace(/\D/g, '').slice(0, length)
     if (value === undefined) setInternalValue(cleaned)
     onChangeRef.current?.(cleaned)
   }
 
-  const complete = current.length === length && /^\d+$/.test(current)
-
-  useEffect(() => {
-    if (!complete) {
-      completed.current = false
-      completedValue.current = null
-      setPhase('idle')
-      return
-    }
-    if (completed.current && completedValue.current === current) return
-    completed.current = true
-    completedValue.current = current
-    setPhase('success')
-    onCompleteRef.current?.(current)
-  }, [complete, current, length])
-
-  useEffect(() => {
-    if (!error) return
-    completed.current = false
-    completedValue.current = null
-    setPhase('idle')
-  }, [error])
-
-  useEffect(() => {
-    if (autoFocus) inputs.current[0]?.focus()
-  }, [autoFocus])
-
   const focusInput = (index: number) => {
     inputs.current[Math.max(0, Math.min(length - 1, index))]?.focus()
     inputs.current[Math.max(0, Math.min(length - 1, index))]?.select()

package/src/components/ui/stories-tokens.ts

@@ -0,0 +1,18 @@
+const accentToScheme: Record<string, { dark: string; light: string; foreground: string; background: string }> = {
+  '#10b981': {
+    dark: '#0f172a',
+    light: '#0f172a',
+    foreground: '#f1f5f9',
+    background: '#ecfdf5',
+  },
+  default: {
+    dark: '#f8fafc',
+    light: '#0f172a',
+    foreground: '#0f172a',
+    background: '#ffffff',
+  },
+}
+
+export function accentTokens(accent: string) {
+  return accentToScheme[accent] ?? accentToScheme.default
+}

package/src/components/ui/stories.tsx

@@ -50,6 +50,11 @@ export function Stories({
 
   const setOpen = useCallback(
     (next: boolean) => {
+      if (next) {
+        // Réinitialise la lecture à l'ouverture plutôt que par un effet.
+        elapsedRef.current = 0
+        setPaused(false)
+      }
       if (open === undefined) setInternalOpen(next)
       onOpenChange?.(next)
     },
@@ -76,13 +81,6 @@ export function Stories({
 
   const close = useCallback(() => setOpen(false), [setOpen])
 
-  useEffect(() => {
-    if (!isOpen) return
-    setIndex(initialIndex)
-    setPaused(false)
-    elapsedRef.current = 0
-  }, [initialIndex, isOpen])
-
   useEffect(() => {
     if (!isOpen) return
     const previous = document.body.style.overflow
@@ -115,14 +113,19 @@ export function Stories({
     else void video.play().catch(() => {})
   }, [index, isOpen, paused])
 
+  const mainLoopRef = useRef<{ startedAt: number; total: number } | null>(null)
+
   useEffect(() => {
     if (!isOpen || paused) return
     if (barRef.current) barRef.current.style.transform = 'scaleX(0)'
 
-    const total = items[index]?.duration ?? duration
+    const item = items[index]
+    const total = item?.duration ?? duration
     const startedAt = performance.now() - elapsedRef.current
-    let frame = 0
 
+    mainLoopRef.current = { startedAt, total }
+
+    let frame = 0
     const tick = (now: number) => {
       const elapsed = now - startedAt
       elapsedRef.current = elapsed

package/src/components/ui/video-player.tsx

@@ -27,12 +27,14 @@ import {
 } from 'lucide-react'
 import type Hls from 'hls.js'
 import { cn } from '@/lib/utils'
+import type {
+  ResolvedSubtitleTrack,
+  SubtitleTrack,
+} from '@/lib/vtt'
 import {
   parseVtt,
   subtitleSignature,
   toSubtitleList,
-  type ResolvedSubtitleTrack,
-  type SubtitleTrack,
 } from '@/lib/vtt'
 import {
   buildEmbedUrl,
@@ -55,6 +57,9 @@ import {
   type ResolvedSource,
   type SourceKind,
 } from '@/lib/video'
+import {
+  useControllableValue,
+} from '@/lib/use-controllable'
 
 export type VideoControlsMode = 'none' | 'minimal' | 'full'
 export type VideoRounded = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
@@ -163,44 +168,82 @@ const rangeThumb =
   '[&::-webkit-slider-thumb]:size-2.5 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:rounded-sm [&::-webkit-slider-thumb]:border-0 [&::-webkit-slider-thumb]:bg-[var(--vp-accent)] [&::-moz-range-thumb]:size-2.5 [&::-moz-range-thumb]:appearance-none [&::-moz-range-thumb]:rounded-sm [&::-moz-range-thumb]:border-0 [&::-moz-range-thumb]:bg-[var(--vp-accent)]'
 
 /** Transforme les sources (URL, File, Blob, qualités) en sources lisibles et gère les object URLs. */
-function useResolvedSources(input: PlayerSource | PlayerSource[]) {
-  const signature = useMemo(() => sourceSignature(input), [input])
-
-  const [sources, setSources] = useState<ResolvedSource[]>([])
+interface SourceResolver {
+  sources: ResolvedSource[]
+  signature: string
+  /** Révoque les object URLs créées pour cette résolution. */
+  dispose: () => void
+}
 
-  // La signature résume `input` : l'effet ne tourne que lorsqu'une source change réellement.
-  useEffect(() => {
-    const created: string[] = []
-    const next = toSourceList(input).map<ResolvedSource>((source) => {
-      if (typeof source === 'string') {
-        return { src: source, kind: detectKind(source) }
-      }
-      if (source instanceof Blob) {
-        const url = URL.createObjectURL(source)
-        created.push(url)
-        return {
-          src: url,
-          kind: 'native',
-          objectUrl: true,
-          type: source.type || undefined,
-        }
-      }
+function resolveSources(input: PlayerSource | PlayerSource[]): SourceResolver {
+  const signature = sourceSignature(input)
+  const created: string[] = []
+  const sources: ResolvedSource[] = toSourceList(input).map<ResolvedSource>((source) => {
+    if (typeof source === 'string') {
+      return { src: source, kind: detectKind(source) }
+    }
+    if (source instanceof Blob) {
+      const url = URL.createObjectURL(source)
+      created.push(url)
       return {
-        src: source.src,
-        kind: detectKind(source.src, source.type),
-        type: source.type,
-        quality: source.quality,
+        src: url,
+        kind: 'native',
+        objectUrl: true,
+        type: source.type || undefined,
       }
-    })
-
-    setSources(next)
+    }
+    return {
+      src: source.src,
+      kind: detectKind(source.src, source.type),
+      type: source.type,
+      quality: source.quality,
+    }
+  })
 
-    return () => {
+  return {
+    sources,
+    signature,
+    dispose: () => {
       for (const url of created) URL.revokeObjectURL(url)
+    },
+  }
+}
+
+/** Piste active par défaut : celle marquée `default`, sinon la première avec des cues. */
+function preferDefaultActiveSubtitle(
+  loaded: ResolvedSubtitleTrack[],
+  list: SubtitleTrack[],
+): number | null {
+  const defaultIndex = list.findIndex((track) => track.default)
+  if (defaultIndex >= 0 && loaded[defaultIndex]?.cues.length) return defaultIndex
+  const firstWithCues = loaded.findIndex((track) => track.cues.length > 0)
+  return firstWithCues >= 0 ? firstWithCues : null
+}
+
+function useResolvedSources(input: PlayerSource | PlayerSource[]) {
+  const signature = sourceSignature(input)
+  const [entry, setEntry] = useState<{ signature: string; resolver: SourceResolver }>(() => ({
+    signature,
+    resolver: resolveSources(input),
+  }))
+
+  // Ajustement au rendu quand la source change réellement (pas d'effet).
+  if (entry.signature !== signature) {
+    setEntry({ signature, resolver: resolveSources(input) })
+  }
+
+  const resolver = entry.resolver
+  // Libère les object URLs du résolveur remplacé (celui du montage n'est pas
+  // libéré au démontage : StrictMode simulerait un unmount/remount).
+  const previousResolver = useRef(resolver)
+  useEffect(() => {
+    if (previousResolver.current !== resolver) {
+      previousResolver.current.dispose()
+      previousResolver.current = resolver
     }
-  }, [signature])
+  }, [resolver])
 
-  return { sources, signature }
+  return { sources: resolver.sources, signature: resolver.signature }
 }
 
 export function VideoPlayer({
@@ -254,12 +297,12 @@ export function VideoPlayer({
 
   const [index, setIndex] = useState(0)
   const [playing, setPlaying] = useState(false)
-  const [muted, setMuted] = useState(mutedProp)
-  const [volume, setVolumeState] = useState(clamp(volumeProp, 0, 1))
+  const [muted, setMuted] = useControllableValue<boolean>(mutedProp, mutedProp)
+  const [volume, setVolumeState] = useControllableValue<number>(volumeProp, clamp(volumeProp, 0, 1))
   const [currentTime, setCurrentTime] = useState(0)
   const [duration, setDuration] = useState(0)
   const [buffered, setBuffered] = useState(0)
-  const [rate, setRate] = useState(playbackRate)
+  const [rate, setRate] = useControllableValue<number>(playbackRate, playbackRate)
   const [fullscreen, setFullscreen] = useState(false)
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
@@ -268,18 +311,43 @@ export function VideoPlayer({
   const [embedActive, setEmbedActive] = useState(false)
   const [embedPlaying, setEmbedPlaying] = useState(false)
   const [embedSrc, setEmbedSrc] = useState<string | null>(null)
-  const [subtitleTracks, setSubtitleTracks] = useState<ResolvedSubtitleTrack[]>([])
-  const [activeSubtitle, setActiveSubtitle] = useState(-1)
   const [openMenu, setOpenMenu] = useState<'speed' | 'quality' | 'subtitles' | null>(null)
-  const [controlsVisible, setControlsVisible] = useState(true)
+  const [controlsHidden, setControlsHidden] = useState(false)
   const [failedThumbKey, setFailedThumbKey] = useState<string | null>(null)
   const [retryKey, setRetryKey] = useState(0)
+  const [prevSignature, setPrevSignature] = useState(signature)
+
+  // Ajustement au rendu : la source change ⇒ on repart d'un état propre,
+  // sans effet ni render supplémentaire.
+  if (prevSignature !== signature) {
+    setPrevSignature(signature)
+    setIndex(0)
+    setError(null)
+    setLoading(true)
+    setEmbedActive(false)
+    setEmbedPlaying(false)
+    setEmbedSrc(null)
+    setPlaying(false)
+    setCurrentTime(0)
+    setDuration(0)
+    setBuffered(0)
+  }
 
   const subtitleSig = useMemo(
     () => (subtitles ? subtitleSignature(subtitles) : ''),
     [subtitles],
   )
 
+  // Les pistes déjà chargées ne correspondent plus à la signature courante :
+  // on les écarte pendant le rechargement plutôt que par un effet de reset.
+  const [loadedSubtitles, setLoadedSubtitles] = useState<{
+    sig: string
+    tracks: ResolvedSubtitleTrack[]
+  } | null>(null)
+  const [activeSubtitle, setActiveSubtitle] = useState(-1)
+  const subtitleTracks =
+    loadedSubtitles && loadedSubtitles.sig === subtitleSig ? loadedSubtitles.tracks : []
+
   const controlMode: VideoControlsMode =
     controls === true ? 'full' : controls === false ? 'none' : controls
 
@@ -295,12 +363,13 @@ export function VideoPlayer({
         : vimeoId(active.src)
       : null
 
-  const shouldLoad = inView || !lazy
+  const observerSupported = typeof IntersectionObserver !== 'undefined'
+  const shouldLoad = inView || !lazy || !observerSupported
   const playbackActive = isEmbed ? embedPlaying : playing
   // L'iframe ne transmet pas les mouvements du pointeur : pour un embed, la barre
   // reste affichée, sinon elle ne pourrait plus jamais être rappelée.
   const showControls =
-    isEmbed || controlsVisible || !playbackActive || openMenu !== null
+    isEmbed || !controlsHidden || !playbackActive || openMenu !== null
 
   const progress = duration > 0 ? clamp((currentTime / duration) * 100, 0, 100) : 0
   const bufferedPercent = duration > 0 ? clamp((buffered / duration) * 100, 0, 100) : 0
@@ -347,32 +416,25 @@ export function VideoPlayer({
     [embedKind, postEmbed],
   )
 
-  // Dernier état voulu, réappliqué à chaque tentative de handshake : le lecteur
-  // de la plateforme ignore les commandes envoyées avant d'être prêt.
-  const embedSettings = useRef({ muted, volume, rate })
-  useEffect(() => {
-    embedSettings.current = { muted, volume, rate }
-  })
-
   /** Abonne le lecteur aux événements de l'iframe (temps, durée, état, volume). */
   const sendEmbedHandshake = useCallback(() => {
     if (!embedKind) return
     for (const message of embedHandshake(embedKind)) postEmbed(message)
 
-    const settings = embedSettings.current
-    postEmbedCommand({ type: 'mute', muted: settings.muted })
-    postEmbedCommand({ type: 'volume', volume: settings.volume })
-    postEmbedCommand({ type: 'rate', rate: settings.rate })
-  }, [embedKind, postEmbed, postEmbedCommand])
+    postEmbedCommand({ type: 'mute', muted: muted })
+    postEmbedCommand({ type: 'volume', volume })
+    postEmbedCommand({ type: 'rate', rate })
+  }, [embedKind, postEmbed, postEmbedCommand, muted, volume, rate])
 
   /** Monte l'iframe (façade → lecteur) : la lecture démarre avec le geste de l'utilisateur. */
   const startEmbed = useCallback(() => {
     if (!embedId || !embedKind) return
+    const effectiveMuted = muted ?? mutedProp
     setEmbedSrc(
       buildEmbedUrl(embedKind, embedId, {
         startAt,
         loop,
-        muted,
+        muted: effectiveMuted,
         controls: false,
         origin: window.location.origin.startsWith('http') ? window.location.origin : undefined,
       }),
@@ -380,7 +442,7 @@ export function VideoPlayer({
     setEmbedActive(true)
     setEmbedPlaying(true)
     setCurrentTime(startAt)
-  }, [embedId, embedKind, loop, muted, startAt])
+  }, [embedId, embedKind, loop, muted, mutedProp, startAt])
 
   const toggleEmbedPlay = useCallback(() => {
     // L'iframe n'est pas encore montée : on la lance au lieu d'envoyer une commande dans le vide.
@@ -444,7 +506,7 @@ export function VideoPlayer({
       video.volume = next
       video.muted = next === 0
     }
-  }, [])
+  }, [setMuted, setVolumeState])
 
   const toggleMute = useCallback(() => {
     setMuted((previous) => {
@@ -453,7 +515,7 @@ export function VideoPlayer({
       if (video) video.muted = next
       return next
     })
-  }, [])
+  }, [setMuted])
 
   const changeRate = useCallback(
     (value: number) => {
@@ -463,7 +525,7 @@ export function VideoPlayer({
       if (isEmbed) postEmbedCommand({ type: 'rate', rate: value })
       setOpenMenu(null)
     },
-    [isEmbed, postEmbedCommand],
+    [isEmbed, postEmbedCommand, setRate],
   )
 
   const toggleFullscreen = useCallback(() => {
@@ -548,33 +610,21 @@ export function VideoPlayer({
       requestFullscreen: () => toggleFullscreen(),
       getVideo: () => videoRef.current,
     }),
-    [changeRate, changeVolume, isEmbed, postEmbedCommand, seekTo, toggleFullscreen],
+    [changeRate, changeVolume, isEmbed, postEmbedCommand, seekTo, setMuted, toggleFullscreen],
   )
 
   /* ------------------------------------------------------------------ */
   /* Synchronisation des props / de l'état                               */
   /* ------------------------------------------------------------------ */
 
+  // La réinitialisation d'état se fait au rendu (voir ci-dessus) ; on ne garde
+  // ici que les refs, qui ne doivent pas être écrites pendant le rendu.
   useEffect(() => {
-    setIndex(0)
     startApplied.current = null
-    setError(null)
-    setLoading(true)
-    setEmbedActive(false)
-    setEmbedPlaying(false)
-    setEmbedSrc(null)
-    setPlaying(false)
-    setCurrentTime(0)
-    setDuration(0)
-    setBuffered(0)
   }, [signature])
 
   useEffect(() => {
-    if (!subtitles) {
-      setSubtitleTracks([])
-      setActiveSubtitle(-1)
-      return
-    }
+    if (!subtitles) return
 
     const list = toSubtitleList(subtitles)
     const urls: string[] = []
@@ -600,10 +650,9 @@ export function VideoPlayer({
       )
 
       if (cancelled) return
-      setSubtitleTracks(loaded)
-      const preferred = list.findIndex((track) => track.default)
+      setLoadedSubtitles({ sig: subtitleSig, tracks: loaded })
       setActiveSubtitle(
-        preferred >= 0 && loaded[preferred] ? preferred : loaded.length > 0 ? 0 : -1,
+        preferDefaultActiveSubtitle(loaded, list) ?? -1,
       )
     }
 
@@ -613,15 +662,11 @@ export function VideoPlayer({
       cancelled = true
       for (const url of urls) URL.revokeObjectURL(url)
     }
-  }, [subtitleSig])
-
-  useEffect(() => {
-    setMuted(mutedProp)
-  }, [mutedProp])
+  }, [subtitles, subtitleSig])
 
   useEffect(() => {
     if (!isEmbed || !embedActive) return
-    postEmbedCommand({ type: 'mute', muted })
+    postEmbedCommand({ type: 'mute', muted: muted })
   }, [embedActive, isEmbed, muted, postEmbedCommand])
 
   useEffect(() => {
@@ -661,42 +706,28 @@ export function VideoPlayer({
     }
     window.addEventListener('message', onMessage)
     return () => window.removeEventListener('message', onMessage)
-  }, [embedActive, embedKind, isEmbed])
+  }, [embedActive, embedKind, isEmbed, setRate])
 
   useEffect(() => {
     if (embedKind !== 'vimeo' || !embedActive) return
     postEmbed({ method: 'setLoop', value: loop })
   }, [embedActive, embedKind, loop, postEmbed])
 
-  useEffect(() => {
-    setVolumeState(clamp(volumeProp, 0, 1))
-  }, [volumeProp])
-
-  useEffect(() => {
-    setRate(playbackRate)
-  }, [playbackRate])
-
   useEffect(() => {
     const video = videoRef.current
     if (!video) return
-    video.volume = volume
-    video.muted = muted || volume === 0
-  }, [muted, volume])
+    video.volume = volume ?? volumeProp
+    video.muted = (muted ?? mutedProp) || (volume ?? volumeProp) === 0
+  }, [muted, mutedProp, volume, volumeProp])
 
   useEffect(() => {
     if (videoRef.current) videoRef.current.playbackRate = rate
   }, [rate])
 
   useEffect(() => {
-    if (!lazy) {
-      setInView(true)
-      return
-    }
+    if (!lazy || !observerSupported) return
     const element = containerRef.current
-    if (!element || typeof IntersectionObserver === 'undefined') {
-      setInView(true)
-      return
-    }
+    if (!element) return
     const observer = new IntersectionObserver(
       (entries) => {
         const entry = entries[0]
@@ -714,11 +745,12 @@ export function VideoPlayer({
     )
     observer.observe(element)
     return () => observer.disconnect()
-  }, [isEmbed, lazy, postEmbedCommand])
+  }, [isEmbed, lazy, observerSupported, postEmbedCommand])
 
   useEffect(() => {
     if (!autoPlay || kind === 'hls' || isEmbed || !shouldLoad) return
-    void attemptPlay()
+    const timer = window.setTimeout(() => void attemptPlay(), 0)
+    return () => window.clearTimeout(timer)
   }, [attemptPlay, autoPlay, isEmbed, kind, shouldLoad, active?.src])
 
   useEffect(() => {
@@ -735,31 +767,39 @@ export function VideoPlayer({
   }, [playbackActive])
 
   const scheduleHide = useCallback(() => {
-    setControlsVisible(true)
+    setControlsHidden(false)
     if (hideTimer.current) window.clearTimeout(hideTimer.current)
     hideTimer.current = window.setTimeout(() => {
-      if (playbackActiveRef.current) setControlsVisible(false)
+      if (playbackActiveRef.current) setControlsHidden(true)
     }, 2600)
   }, [])
 
+  // À la reprise de lecture, les contrôles repartent visibles : ajustement au
+  // rendu plutôt qu'un setState synchrone dans l'effet.
+  const [prevPlaybackActive, setPrevPlaybackActive] = useState(playbackActive)
+  if (prevPlaybackActive !== playbackActive) {
+    setPrevPlaybackActive(playbackActive)
+    if (playbackActive) setControlsHidden(false)
+  }
+
+  // L'effet ne fait qu'armer le minuteur (système externe) ; le reveal est
+  // géré par les événements pointeur ou par l'ajustement au rendu ci-dessus.
   useEffect(() => {
     if (!playbackActive) {
-      setControlsVisible(true)
       if (hideTimer.current) {
         window.clearTimeout(hideTimer.current)
         hideTimer.current = null
       }
       return
     }
-    scheduleHide()
+    if (hideTimer.current) window.clearTimeout(hideTimer.current)
+    hideTimer.current = window.setTimeout(() => {
+      if (playbackActiveRef.current) setControlsHidden(true)
+    }, 2600)
     return () => {
       if (hideTimer.current) window.clearTimeout(hideTimer.current)
     }
-  }, [playbackActive, scheduleHide])
-
-  useEffect(() => {
-    if (openMenu) setControlsVisible(true)
-  }, [openMenu])
+  }, [playbackActive])
 
   useEffect(() => {
     if (!openMenu) return
@@ -885,7 +925,7 @@ export function VideoPlayer({
 
   const handleEnded = () => {
     setPlaying(false)
-    setControlsVisible(true)
+    setControlsHidden(false)
     onEnded?.()
   }
 
@@ -949,7 +989,7 @@ export function VideoPlayer({
 
   const handlePointerActivity = () => {
     if (!playbackActive) {
-      setControlsVisible(true)
+      setControlsHidden(false)
       return
     }
     scheduleHide()

package/src/lib/use-controllable.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * Retourne un état local piloté par une prop quand celle-ci est explicite.
+ *
+ * Quand le parent fournit explicitement la prop, l'état local se
+ * synchronise dessus. Quand la prop est `undefined`, le composant garde
+ * sa propre valeur locale.
+ *
+ * Cette version est compatible avec React Compiler : elle n'accède jamais
+ * aux refs pendant le rendu.
+ */
+export function useControllableValue<T>(
+  prop: T | undefined,
+  defaultState: T,
+  onChange?: (value: T) => void,
+) {
+  const [state, setState] = useState<T>(defaultState)
+  const controlledRef = useRef<boolean>(prop !== undefined)
+  const previousPropRef = useRef<T | undefined>(prop)
+
+  const isControlled = prop !== undefined
+
+  // Synchronise l'état local quand le contrôle parent change.
+  useEffect(() => {
+    controlledRef.current = isControlled
+    previousPropRef.current = prop
+  })
+
+  // Premier rendu contrôlé : la prop doit remplacer l'état local.
+  // Passages ultérieurs : synchronise seulement si la prop a changé.
+  useEffect(() => {
+    if (!isControlled) return
+    const next = prop as T
+    if (next !== previousPropRef.current) setState(next)
+  }, [isControlled, prop, state])
+
+  const value = isControlled ? (prop as T) : state
+
+  const setValue = useCallback(
+    (next: T | ((previous: T) => T)) => {
+      const resolved = typeof next === 'function' ? (next as (p: T) => T)(state) : next
+      if (isControlled) {
+        if (resolved !== prop) onChange?.(resolved)
+        return
+      }
+      setState(resolved)
+      onChange?.(resolved)
+    },
+    [isControlled, onChange, prop, state],
+  )
+
+  return [value, setValue] as const
+}

package/src/lib/video.ts

@@ -70,29 +70,29 @@ export function youtubeThumbnail(id: string): string {
 
 export function youtubeThumbnailFallback(id: string): string {
   return `https://i.ytimg.com/vi/${id}/hqdefault.jpg`
-}
-
-export interface EmbedOptions {
+}export interface EmbedOptions {
   startAt?: number
   loop?: boolean
   muted?: boolean
   controls?: boolean
   /** Origine de la page hôte : l'API iframe YouTube lui associe les commandes postMessage. */
   origin?: string
+  playsinline?: boolean
 }
 
+
 export function buildEmbedUrl(
   kind: 'youtube' | 'vimeo',
   id: string,
   options: EmbedOptions = {},
 ): string {
-  const { startAt = 0, loop = false, muted = false, controls = true, origin } = options
+  const { startAt = 0, loop = false, muted = false, controls = true, origin, playsinline = true } = options
 
   if (kind === 'youtube') {
     const params = new URLSearchParams({
       autoplay: '1',
       rel: '0',
-      playsinline: '1',
+      playsinline: playsinline ? '1' : '0',
       modestbranding: '1',
       enablejsapi: '1',
       controls: controls ? '1' : '0',
@@ -121,6 +121,7 @@ export function buildEmbedUrl(
   return `https://player.vimeo.com/video/${id}?${params.toString()}${hash}`
 }
 
+
 /* -------------------------------------------------------------------------- */
 /* Pilotage des embeds (YouTube / Vimeo) par postMessage                      */
 /* -------------------------------------------------------------------------- */