create-theokit 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/surfaces/tui/tui/App.tsx.tmpl

@@ -1,10 +1,12 @@
 import { Box, Text, useApp, useInput } from 'ink'
-import { type ReactElement } from 'react'
+import { type ReactElement, useState } from 'react'
 import {
   AgentStreaming,
   AgentTimeline,
   AppStatusBar,
   ChatComposer,
+  DEFAULT_COMPOSER_SHORTCUTS,
+  KeyboardHelp,
   messagesToAgentEvents,
   readTurnUsage,
   TheoTUIProvider,
@@ -29,7 +31,7 @@ const GREETING: UIMessageLike = {
   parts: [
     {
       type: 'text',
-      text: `${AGENT.greeting} Type below and press Enter · /clear resets · esc cancels.`,
+      text: `${AGENT.greeting} Type below and press Enter · / for commands · @ to mention a file · ? for help.`,
     },
   ],
 }
@@ -57,6 +59,10 @@ export function App(): ReactElement {
   const streaming = agent.status === 'streaming'
   const elapsed = useTurnElapsed(streaming)
   const { exit } = useApp()
+  const [showHelp, setShowHelp] = useState(false)
+  // Ctrl+C is a two-step quit (Claude Code): the first press arms the exit + shows a hint, the second
+  // quits. Any other key disarms. `render(<App/>, { exitOnCtrlC: false })` in main.tsx hands us Ctrl+C.
+  const [exitArmed, setExitArmed] = useState(false)
 
   // The store owns the conversation (M46) — prepend the warm greeting and project to timeline events.
   const events = messagesToAgentEvents([GREETING, ...agent.thread])
@@ -69,11 +75,24 @@ export function App(): ReactElement {
   const sessionCost = usages.reduce((sum, u) => sum + (u.cost ?? 0), 0)
   const tokens = lastUsage ? { used: lastUsage.inputTokens, limit: AGENT.contextWindow } : undefined
 
-  // Esc cancels a running turn, or quits when idle (the Claude Code affordance).
-  useInput((_input, key) => {
-    if (!key.escape) return
-    if (streaming) agent.abort()
-    else exit()
+  // Global keys. Esc cancels a running turn / closes the help panel. Ctrl+C cancels a turn, else arms →
+  // quits on a second press. The ChatComposer owns the editing keys (/, @, !, ?, history ↑↓, emacs chords).
+  useInput((input, key) => {
+    if (key.escape) {
+      if (showHelp) setShowHelp(false)
+      else if (streaming) agent.abort()
+      return
+    }
+    if (key.ctrl && input === 'c') {
+      if (streaming) {
+        agent.abort()
+        return
+      }
+      if (exitArmed) exit()
+      else setExitArmed(true)
+      return
+    }
+    if (exitArmed) setExitArmed(false)
   })
 
   const handleSubmit = (text: string): void => {
@@ -83,6 +102,10 @@ export function App(): ReactElement {
       agent.reset()
       return
     }
+    if (trimmed === '/help') {
+      setShowHelp((h) => !h)
+      return
+    }
     agent.send({ message: trimmed })
   }
 
@@ -92,7 +115,7 @@ export function App(): ReactElement {
         <WelcomeBanner
           name="{{name}}"
           tagline="Your agent, in the terminal — built with TheoKit."
-          hints={['Enter sends · Alt+Enter for a newline', '/clear resets · esc cancels a turn or quits']}
+          hints={['Enter sends · Alt+Enter for a newline', '/ commands · @ files · ? help · ctrl+c quits']}
         >
           <Text dimColor>cwd: {CWD}</Text>
         </WelcomeBanner>
@@ -102,11 +125,21 @@ export function App(): ReactElement {
         {streaming ? <AgentStreaming thought="Thinking…" elapsedSeconds={elapsed} showCancelHint /> : null}
         {agent.error ? <Text color="red">⚠ {agent.error.message}</Text> : null}
 
+        {showHelp ? <KeyboardHelp shortcuts={DEFAULT_COMPOSER_SHORTCUTS} /> : null}
+
         <ChatComposer
-          placeholder="Ask your agent…  (Enter sends · / commands · @ files)"
+          placeholder="Ask your agent…  (Enter sends · / commands · @ files · ? help)"
           bordered
-          hint="Enter sends · Alt+Enter newline · /clear resets · esc cancels"
-          commands={[{ name: 'clear', description: 'clear the conversation' }]}
+          hint={
+            exitArmed
+              ? 'Press Ctrl+C again to quit'
+              : 'Enter sends · Alt+Enter newline · / commands · @ files · ? help · esc cancels'
+          }
+          commands={[
+            { name: 'clear', description: 'clear the conversation' },
+            { name: 'help', description: 'toggle the keyboard shortcuts panel' },
+          ]}
+          onHelpToggle={() => setShowHelp((h) => !h)}
           onSubmit={handleSubmit}
         />
 

package/templates/surfaces/tui/tui/main.tsx.tmpl

@@ -11,4 +11,6 @@ if (typeof process.loadEnvFile === 'function') {
   }
 }
 
-render(<App />)
+// `exitOnCtrlC: false` so the App owns Ctrl+C — a single press cancels a running turn, a double press
+// quits (the Claude Code affordance). Without this, Ink would hard-exit on the first Ctrl+C.
+render(<App />, { exitOnCtrlC: false })