feat(core): add interactive mode and key binding hooks

.changeset/interactive-story-mode.md

@@ -0,0 +1,13 @@
+---
+'@kidd-cli/core': minor
+---
+
+feat(core): add interactive mode and declarative key binding hooks
+
+Adds interactive mode to the stories viewer, giving story components full terminal control with the header and sidebar hidden. Press `i` to enter interactive mode and double-press `Esc` to exit.
+
+Introduces reusable key handling primitives:
+
+- **keys.ts**: shared key vocabulary, pattern parser, and normalizer for Ink's `useInput`
+- **useKeyBinding**: declarative keymap hook supporting single keys, modifier combos, and multi-key sequences
+- **useKeyInput**: enhanced raw input hook with normalized key events

examples/diagnostic-output/package.json

@@ -18,4 +18,4 @@
     "tsx": "catalog:",
     "typescript": "catalog:"
   }
-}
+}

packages/core/src/stories/viewer/components/help-overlay.tsx

@@ -8,6 +8,7 @@ import type { ReactElement } from 'react'
 const BROWSE_SHORTCUTS = [
   { key: 'Up/Down', description: 'Navigate story tree' },
   { key: 'Enter', description: 'Select story / expand-collapse group' },
+  { key: 'i', description: 'Enter interactive mode' },
   { key: 'b', description: 'Toggle sidebar' },
   { key: 'r', description: 'Reset props to defaults' },
   { key: '?', description: 'Toggle help' },
@@ -24,6 +25,8 @@ const EDIT_SHORTCUTS = [
   { key: 'q', description: 'Quit' },
 ] as const
 
+const INTERACTIVE_SHORTCUTS = [{ key: 'Esc Esc', description: 'Exit interactive mode' }] as const
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -80,6 +83,18 @@ export function HelpOverlay({ onClose }: HelpOverlayProps): ReactElement {
           <Text>{shortcut.description}</Text>
         </Box>
       ))}
+      <Text> </Text>
+      <Text bold color="green">
+        Interactive Mode
+      </Text>
+      {INTERACTIVE_SHORTCUTS.map((shortcut) => (
+        <Box key={shortcut.key} gap={2}>
+          <Box width={12}>
+            <Text color="cyan">{shortcut.key}</Text>
+          </Box>
+          <Text>{shortcut.description}</Text>
+        </Box>
+      ))}
     </Box>
   )
 }

packages/core/src/stories/viewer/components/preview.tsx

@@ -48,6 +48,7 @@ interface PreviewProps {
   readonly onPropsChange: (name: string, value: unknown) => void
   readonly isFocused: boolean
   readonly borderless?: boolean
+  readonly interactive?: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -75,6 +76,7 @@ export function Preview({
   onPropsChange,
   isFocused,
   borderless = false,
+  interactive = false,
 }: PreviewProps): ReactElement {
   const contentRef = useRef<DOMElement>(null)
   const { height: contentHeight } = useSize(contentRef)
@@ -115,6 +117,16 @@ export function Preview({
     )
   }
 
+  if (interactive) {
+    return (
+      <Box flexDirection="column" flexGrow={1} overflow="hidden">
+        <ErrorBoundary key={context.displayName}>
+          <DecoratedComponent {...currentProps} />
+        </ErrorBoundary>
+      </Box>
+    )
+  }
+
   return (
     <Box
       flexDirection="column"

packages/core/src/stories/viewer/components/status-bar.tsx

@@ -45,6 +45,7 @@ export function StatusBar({ mode, hasSelection, isReloading }: StatusBarProps):
           <BrowseHints hasSelection={hasSelection} />
         ))
         .with({ isReloading: false, mode: 'edit' }, () => <EditHints />)
+        .with({ isReloading: false, mode: 'interactive' }, () => <InteractiveHints />)
         .exhaustive()}
       <Spacer />
       <Text dimColor>q</Text>
@@ -71,11 +72,13 @@ function ModeIndicator({ mode }: { readonly mode: ViewerMode }): ReactElement {
       color={match(mode)
         .with('browse', () => 'cyan' as const)
         .with('edit', () => 'yellow' as const)
+        .with('interactive', () => 'green' as const)
         .exhaustive()}
     >
       {match(mode)
         .with('browse', () => '● Browse')
         .with('edit', () => '● Edit')
+        .with('interactive', () => '● Interactive')
         .exhaustive()}
     </Text>
   )
@@ -139,3 +142,18 @@ function EditHints(): ReactElement {
     </Box>
   )
 }
+
+/**
+ * Render keyboard hints for interactive mode.
+ *
+ * @private
+ * @returns A rendered hints element.
+ */
+function InteractiveHints(): ReactElement {
+  return (
+    <Box>
+      <Text dimColor>esc esc</Text>
+      <Text>: exit interactive</Text>
+    </Box>
+  )
+}

packages/core/src/stories/viewer/hooks/use-double-escape.ts

@@ -0,0 +1,43 @@
+/**
+ * Thin wrapper hook that listens for a double-press Escape sequence
+ * and invokes an exit callback. Used by the stories viewer to exit
+ * interactive mode without intercepting single Escape presses.
+ *
+ * @module
+ */
+
+import { useMemo } from 'react'
+
+import type { KeyBinding } from '../../../ui/use-key-binding.js'
+import { useKeyBinding } from '../../../ui/use-key-binding.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the {@link useDoubleEscape} hook.
+ */
+interface DoubleEscapeOptions {
+  readonly onExit: () => void
+  readonly isActive: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+/**
+ * Listen for a double-press Escape sequence and call `onExit` when detected.
+ * The binding is only active when `isActive` is `true`, allowing the caller
+ * to enable it only in interactive mode.
+ *
+ * @param options - The hook options with exit callback and active state.
+ */
+export function useDoubleEscape({ onExit, isActive }: DoubleEscapeOptions): void {
+  const bindings = useMemo<readonly KeyBinding[]>(
+    () => [{ keys: 'escape escape', action: onExit }],
+    [onExit]
+  )
+  useKeyBinding(bindings, { isActive })
+}

packages/core/src/stories/viewer/hooks/use-panel-focus.ts

@@ -9,8 +9,9 @@ import { useCallback, useState } from 'react'
  *
  * - `browse` — Sidebar is active, user navigates the story tree.
  * - `edit` — Props editor is active, user edits field values.
+ * - `interactive` — Story component has full terminal control.
  */
-export type ViewerMode = 'browse' | 'edit'
+export type ViewerMode = 'browse' | 'edit' | 'interactive'
 
 /**
  * State and controls for managing the viewer interaction mode.
@@ -19,6 +20,8 @@ export interface ViewerModeState {
   readonly mode: ViewerMode
   readonly enterEditMode: () => void
   readonly exitEditMode: () => void
+  readonly enterInteractiveMode: () => void
+  readonly exitInteractiveMode: () => void
 }
 
 // ---------------------------------------------------------------------------
@@ -43,5 +46,13 @@ export function useViewerMode(): ViewerModeState {
     setMode('browse')
   }, [])
 
-  return { mode, enterEditMode, exitEditMode }
+  const enterInteractiveMode = useCallback(() => {
+    setMode('interactive')
+  }, [])
+
+  const exitInteractiveMode = useCallback(() => {
+    setMode('browse')
+  }, [])
+
+  return { mode, enterEditMode, exitEditMode, enterInteractiveMode, exitInteractiveMode }
 }

packages/core/src/stories/viewer/stories-app.tsx

@@ -19,6 +19,7 @@ import { Preview } from './components/preview.js'
 import type { PreviewContext } from './components/preview.js'
 import { Sidebar } from './components/sidebar.js'
 import { StatusBar } from './components/status-bar.js'
+import { useDoubleEscape } from './hooks/use-double-escape.js'
 import { useViewerMode } from './hooks/use-panel-focus.js'
 import { useStories } from './hooks/use-stories.js'
 
@@ -52,7 +53,8 @@ interface StoriesAppProps {
  */
 export function StoriesApp({ registry, isReloading }: StoriesAppProps): ReactElement {
   const entries = useStories(registry)
-  const { mode, enterEditMode, exitEditMode } = useViewerMode()
+  const { mode, enterEditMode, exitEditMode, enterInteractiveMode, exitInteractiveMode } =
+    useViewerMode()
   const [selectedStoryId, setSelectedStoryId] = useState<string | null>(null)
   const [currentProps, setCurrentProps] = useState<Record<string, unknown>>({})
   const [showHelp, setShowHelp] = useState(false)
@@ -126,26 +128,34 @@ export function StoriesApp({ registry, isReloading }: StoriesAppProps): ReactEle
     setShowHelp(false)
   }, [])
 
-  useInput((input, key) => {
-    if (showHelp) {
-      return
-    }
-    if (input === 'q') {
-      exit()
-    }
-    if (key.escape && mode === 'edit') {
-      exitEditMode()
-    }
-    if (input === 'r') {
-      handleResetProps()
-    }
-    if (input === '?') {
-      setShowHelp(true)
-    }
-    if (input === 'b') {
-      setShowSidebar((prev) => !prev)
-    }
-  })
+  useDoubleEscape({ onExit: exitInteractiveMode, isActive: mode === 'interactive' })
+
+  useInput(
+    (input, key) => {
+      if (showHelp) {
+        return
+      }
+      if (input === 'q') {
+        exit()
+      }
+      if (key.escape && mode === 'edit') {
+        exitEditMode()
+      }
+      if (input === 'i' && selectedStoryId !== null) {
+        enterInteractiveMode()
+      }
+      if (input === 'r') {
+        handleResetProps()
+      }
+      if (input === '?') {
+        setShowHelp(true)
+      }
+      if (input === 'b') {
+        setShowSidebar((prev) => !prev)
+      }
+    },
+    { isActive: mode !== 'interactive' }
+  )
 
   if (showHelp) {
     return (
@@ -155,18 +165,28 @@ export function StoriesApp({ registry, isReloading }: StoriesAppProps): ReactEle
     )
   }
 
+  const isInteractive = mode === 'interactive'
+
   return (
     <FullScreen>
       <Box flexDirection="column" flexGrow={1}>
-        <Header />
+        {match(isInteractive)
+          .with(false, () => <Header />)
+          .with(true, () => null)
+          .exhaustive()}
         <Box flexDirection="row" flexGrow={1} overflow="hidden">
-          <Sidebar
-            entries={entries}
-            selectedId={selectedStoryId}
-            onSelect={handleSelect}
-            isFocused={mode === 'browse' && showSidebar}
-            hidden={!showSidebar}
-          />
+          {match(isInteractive)
+            .with(false, () => (
+              <Sidebar
+                entries={entries}
+                selectedId={selectedStoryId}
+                onSelect={handleSelect}
+                isFocused={mode === 'browse' && showSidebar}
+                hidden={!showSidebar}
+              />
+            ))
+            .with(true, () => null)
+            .exhaustive()}
           <Box flexDirection="column" flexGrow={1}>
             {match(isReloading)
               .with(true, () => <ReloadOverlay />)
@@ -179,7 +199,8 @@ export function StoriesApp({ registry, isReloading }: StoriesAppProps): ReactEle
                   errors={errors}
                   onPropsChange={handlePropsChange}
                   isFocused={mode === 'edit'}
-                  borderless={!showSidebar}
+                  borderless={isInteractive || !showSidebar}
+                  interactive={isInteractive}
                 />
               ))
               .exhaustive()}

packages/core/src/test/context.ts

@@ -169,16 +169,20 @@ export function mockStatus(spinnerOverride?: Spinner): Status {
       isCancelled: false,
     })),
     tasks: vi.fn(async () => {}),
-    taskLog: vi.fn((): TaskLogHandle => ({
-      message: vi.fn(),
-      success: vi.fn(),
-      error: vi.fn(),
-      group: vi.fn((): TaskLogGroupHandle => ({
+    taskLog: vi.fn(
+      (): TaskLogHandle => ({
         message: vi.fn(),
         success: vi.fn(),
         error: vi.fn(),
-      })),
-    })),
+        group: vi.fn(
+          (): TaskLogGroupHandle => ({
+            message: vi.fn(),
+            success: vi.fn(),
+            error: vi.fn(),
+          })
+        ),
+      })
+    ),
   } as Status
 }
 

packages/core/src/ui/index.ts

@@ -84,3 +84,9 @@ export type { OutputStore } from './output/index.js'
 
 export { screen } from './screen.js'
 export type { ScreenDef, ScreenExit } from './screen.js'
+
+export { useKeyBinding } from './use-key-binding.js'
+export type { KeyBinding, KeyBindingOptions } from './use-key-binding.js'
+
+export { useKeyInput } from './use-key-input.js'
+export type { KeyInputEvent, KeyInputOptions } from './use-key-input.js'