✨ add disableInitialFocus prop to prevent VS Code from stealing keyboard focus on slide entry

Author: mickaelalvs

README.md

@@ -72,6 +72,16 @@ livecode:
   zoom: 0.8
 ```
 
+## 🎯 Keyboard navigation guard
+
+Use `disableInitialFocus` to prevent VS Code from stealing keyboard focus when you navigate to a slide — arrow keys keep working for Slidev navigation:
+
+```md
+<Editor session="demo" disableInitialFocus />
+```
+
+Focus is held on the slide for 5 seconds after VS Code loads, then released normally. The user can interact with VS Code freely after that.
+
 ## 🔒 Keep the session alive across navigation
 
 By default, navigating away from a slide stops the session. Use `persist` to keep it running:
@@ -108,6 +118,7 @@ Per-component props override these values.
 | `defaultFolder`   | `string`            | project root | Workspace folder to open. Absolute or relative to the Slidev root.         |
 | `colorScheme`     | `'dark' \| 'light'` | auto    | VS Code color theme. Defaults to Slidev's `colorSchema` if set, otherwise none. |
 | `fontSize`        | `number`            | —       | Editor font size. Useful for visibility in large rooms.                         |
+| `disableInitialFocus` | `boolean`       | `false` | Prevent VS Code from stealing keyboard focus on slide entry.                    |
 | `hideActivityBar` | `boolean`           | `false` | Hide the VS Code activity bar (left icon sidebar).                              |
 | `hideMinimap`     | `boolean`           | `false` | Hide the editor minimap.                                                        |
 | `hideStatusBar`   | `boolean`           | `false` | Hide the VS Code status bar (bottom bar).                                       |

components/Editor.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, inject, onBeforeUnmount, shallowRef, watch } from 'vue'
+import { computed, inject, onBeforeUnmount, ref, shallowRef, useAttrs, useTemplateRef, watch } from 'vue'
 import { useIsSlideActive, useNav, useSlideContext } from '@slidev/client'
 
 import { requestStart, requestStop } from '../composables/useStartRequest'
@@ -8,17 +8,12 @@ import { REGISTRY_KEY } from '../setup/main'
 import type { EditorDeckConfig, EditorProps, SessionEntry } from '../types'
 
 const props = withDefaults(defineProps<EditorProps>(), {
-  colorScheme: undefined,
-  defaultFolder: undefined,
-  fontSize: undefined,
+  disableInitialFocus: false,
   height: '100%',
   hideActivityBar: false,
   hideMinimap: false,
   hideStatusBar: false,
   persist: false,
-  port: undefined,
-  session: undefined,
-  startTimeout: undefined,
   zoom: 1,
 })
 
@@ -38,6 +33,11 @@ const { currentPage } = useNav()
 
 const sessionId = props.session ?? `livecode-${currentPage.value}-${props.port ?? 'default'}`
 
+const attrs = useAttrs()
+const isDisableInitialFocus = computed(() =>
+  !!props.disableInitialFocus || 'disableInitialFocus' in attrs || 'disable-initial-focus' in attrs,
+)
+
 const session = shallowRef<SessionEntry | null>(registry.get(sessionId) ?? null)
 
 const isStarting = computed(
@@ -78,6 +78,7 @@ async function start(): Promise<void> {
       resolvedTimeout.value,
     )
     if (entry.state === 'DESTROYED') return
+    if (isDisableInitialFocus.value) startGuard()
     registry!.setRunning(sessionId, url)
   } catch (err) {
     if (entry.state !== 'DESTROYED') registry!.setError(sessionId)
@@ -112,7 +113,40 @@ watch(
   { flush: 'post', immediate: true },
 )
 
+const containerRef = useTemplateRef<HTMLElement>('container')
+const isGuarding = ref(false)
+let guardTimer: ReturnType<typeof setTimeout> | null = null
+
+function handleWindowBlur() {
+  if (!isGuarding.value) return
+  setTimeout(() => containerRef.value?.focus(), 0)
+}
+
+function startGuard() {
+  if (guardTimer) clearTimeout(guardTimer)
+  isGuarding.value = true
+  containerRef.value?.focus()
+  window.addEventListener('blur', handleWindowBlur)
+  guardTimer = setTimeout(() => {
+    isGuarding.value = false
+    window.removeEventListener('blur', handleWindowBlur)
+    guardTimer = null
+  }, 5000)
+}
+
+function stopGuard() {
+  window.removeEventListener('blur', handleWindowBlur)
+  if (guardTimer) { clearTimeout(guardTimer); guardTimer = null }
+  isGuarding.value = false
+}
+
+watch(isActive, (active) => {
+  if (!active || !isDisableInitialFocus.value) { stopGuard(); return }
+  if (session.value?.state === 'RUNNING') startGuard()
+})
+
 onBeforeUnmount(() => {
+  stopGuard()
   if (!props.persist) {
     requestStop(sessionId)
     registry!.teardown(sessionId)
@@ -121,7 +155,7 @@ onBeforeUnmount(() => {
 </script>
 
 <template>
-  <div class="slidev-editor" :style="{ height }">
+  <div ref="container" class="slidev-editor" :style="{ height }" tabindex="-1">
     <template v-if="!$slidev?.nav">
       <div class="slidev-editor-overlay">
         <div class="slidev-editor-overlay-title">IDE not available</div>

showcase/slides.md

@@ -45,54 +45,58 @@ livecode:
 
 # 🚀 Basic usage
 
-<div class="flex-1 rounded-xl overflow-hidden border border-gray-200">
-  <Editor session="demo" />
-</div>
-
----
+Add `<Editor />` to any slide. Use `session` to identify it and `defaultFolder` to set the workspace.
 
-# 📂 Specific workspace
-
-<div class="flex-1 rounded-xl overflow-hidden border border-gray-200">
-  <Editor session="my-project" defaultFolder=".." />
+<div class="flex-1 mt-2 rounded-xl overflow-hidden border border-gray-200">
+  <Editor session="basic" />
 </div>
 
 ---
 
 # 🔒 Persistent session
 
-State is preserved when navigating away and back.
+Use `persist` to keep the session alive when navigating away — state is preserved when you come back.
 
-<div class="flex-1 rounded-xl overflow-hidden border border-gray-200">
-  <Editor session="demo" persist />
+<div class="flex-1 mt-2 rounded-xl overflow-hidden border border-gray-200">
+  <Editor session="persistent" persist />
 </div>
 
 ---
 
-# 📐 Custom height
-
-<Editor session="small" height="300px" />
-
----
-
 # 🔍 Zoom
 
-<div class="flex-1 rounded-xl overflow-hidden border border-gray-200">
-  <Editor session="zoomed" :zoom="0.5" />
+Use `:zoom` to scale down VS Code for a better fit. Can also be set globally in the frontmatter with `livecode.zoom`.
+
+<div class="flex-1 mt-2 rounded-xl overflow-hidden border border-gray-200">
+  <Editor session="zoomed" :zoom="0.7" />
 </div>
 
 ---
 
 # 🌗 Color scheme
 
-<div class="flex-1 rounded-xl overflow-hidden border border-gray-200">
-  <Editor session="dark" colorScheme="dark" />
+Use `colorScheme` to force a dark or light theme. Follows Slidev's `colorSchema` automatically if not set.
+
+<div class="flex-1 mt-2 rounded-xl overflow-hidden border border-gray-200">
+  <Editor session="dark-theme" colorScheme="dark" />
 </div>
 
 ---
 
 # 🔬 Presentation mode
 
-<div class="flex-1 rounded-xl overflow-hidden border border-gray-200">
+Use `fontSize`, `hideMinimap`, `hideActivityBar` and `hideStatusBar` to clean up the UI for a focused demo.
+
+<div class="flex-1 mt-2 rounded-xl overflow-hidden border border-gray-200">
   <Editor session="presentation" :fontSize="18" hideMinimap hideActivityBar hideStatusBar />
 </div>
+
+---
+
+# 🎯 Keyboard navigation
+
+Use `disableInitialFocus` to prevent VS Code from stealing keyboard focus on slide entry — arrow keys keep working.
+
+<div class="flex-1 mt-2 rounded-xl overflow-hidden border border-gray-200">
+  <Editor session="focus-guard" disableInitialFocus />
+</div>

styles/index.css

@@ -16,6 +16,7 @@
   background: var(--slidev-editor-bg);
   border: var(--slidev-editor-border);
   border-radius: var(--slidev-editor-border-radius);
+  outline: none;
   overflow: hidden;
   position: relative;
   width: 100%;

types.ts

@@ -3,6 +3,7 @@ export type SessionState = 'IDLE' | 'STARTING' | 'RUNNING' | 'ERROR' | 'DESTROYE
 export interface EditorProps {
   colorScheme?: 'dark' | 'light'
   defaultFolder?: string
+  disableInitialFocus?: boolean
   fontSize?: number
   height?: string
   hideActivityBar?: boolean