@kidsinai/kids-client 0.0.12 → 0.0.17

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.12",
+  "version": "0.0.17",
   "type": "module",
   "description": "Own-client TUI for Kids OpenCode — talks to local `opencode serve` via @opencode-ai/sdk v2 with kid-warm rendering, mission progress, permission dialog, and stderr-tail audit pipeline.",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "react": "^18.3.1",
-    "@kidsinai/kids-opencode-plugin": "^0.0.1"
+    "@kidsinai/kids-opencode-plugin": "^0.0.17"
   },
   "devDependencies": {
     "@opencode-ai/sdk": "^1.14.51",

package/src/core/course-pack.ts

@@ -7,7 +7,7 @@
  * — used by CoursePackPicker.
  */
 
-import { readdirSync, statSync } from "node:fs"
+import { existsSync, readdirSync, statSync } from "node:fs"
 import { join } from "node:path"
 import {
   bundledCoursePacksDir,
@@ -52,38 +52,62 @@ export interface InstalledPack {
   shortDescription: string | null
   missionCount: number
   starsBudget: number
+  /** Project-type metadata for the picker, surfaced from pack.yml. */
+  icon: string | null
+  pickerLabel: string | null
+  typeCategory: "game" | "website" | "slides" | "video" | null
+  pickerOrder: number
 }
 
 /**
  * Enumerate packs available in the bundled course-packs/ directory. Used
  * by the picker screen. Tolerant of malformed packs (skips, doesn't
  * throw).
+ *
+ * Packs whose folder name starts with `_` (e.g. `_stub`) are hidden from
+ * the picker but remain loadable by id — they're CI fixtures, not kid content.
  */
 export function listInstalledPacks(): InstalledPack[] {
-  const dir = bundledCoursePacksDir()
-  let entries: string[]
-  try {
-    entries = readdirSync(dir)
-  } catch {
-    return []
-  }
+  // Walk both the public dir and the private submodule dir (if mounted).
+  // Same pack id appearing in both is deduped — private wins because the
+  // plugin's packDir() resolves private-first; listing follows the same order.
+  const publicDir = bundledCoursePacksDir()
+  const privateDir = join(publicDir, "private")
+  const dirs = [privateDir, publicDir].filter((d) => existsSync(d))
+  const seen = new Set<string>()
   const out: InstalledPack[] = []
-  for (const id of entries) {
+  for (const dir of dirs) {
+    let entries: string[]
     try {
-      const full = join(dir, id)
-      if (!statSync(full).isDirectory()) continue
-      const pack = loadCoursePack(id)
-      if (!pack) continue
-      out.push({
-        id: pack.id,
-        title: pack.title,
-        shortDescription: pack.short_description ?? null,
-        missionCount: pack.missions?.length ?? 0,
-        starsBudget: pack.estimated_stars_budget ?? 0,
-      })
+      entries = readdirSync(dir)
     } catch {
-      // skip malformed entry
+      continue
+    }
+    for (const id of entries) {
+      if (id.startsWith("_") || id.startsWith(".")) continue
+      if (seen.has(id)) continue
+      try {
+        const full = join(dir, id)
+        if (!statSync(full).isDirectory()) continue
+        const pack = loadCoursePack(id)
+        if (!pack) continue
+        seen.add(id)
+        out.push({
+          id: pack.id,
+          title: pack.title,
+          shortDescription: pack.short_description ?? null,
+          missionCount: pack.missions?.length ?? 0,
+          starsBudget: pack.estimated_stars_budget ?? 0,
+          icon: pack.icon ?? null,
+          pickerLabel: pack.picker_label ?? null,
+          typeCategory: pack.type_category ?? null,
+          pickerOrder: pack.picker_order ?? Number.MAX_SAFE_INTEGER,
+        })
+      } catch {
+        // skip malformed entry
+      }
     }
   }
+  out.sort((a, b) => a.pickerOrder - b.pickerOrder)
   return out
 }

package/src/core/env.ts

@@ -29,6 +29,10 @@ export interface KidsClientEnv {
   coursePack: string | null
   /** Optional mission id (e.g. "mission-1"). */
   mission: string | null
+  /** Optional guided-flow vibe id picked by the kid (e.g. "space"). */
+  vibeId: string | null
+  /** Optional kid-chosen project name. Surfaced in scaffold template vars. */
+  projectName: string | null
   /** Locale hint ("zh-Hans" / "en"). Picked from KIDS_LOCALE or $LANG. */
   locale: "zh-Hans" | "en"
   /** Path to opencode binary so client can spawn `opencode serve`. */
@@ -57,6 +61,8 @@ export function readEnv(): KidsClientEnv {
     bypassGateway: process.env.KIDS_LLM_BYPASS_GATEWAY === "1",
     coursePack: process.env.KIDS_COURSE_PACK || null,
     mission: process.env.KIDS_MISSION || null,
+    vibeId: process.env.KIDS_VIBE_ID || null,
+    projectName: process.env.KIDS_PROJECT_NAME || null,
     locale,
     opencodeBin: process.env.OPENCODE_BIN ?? "opencode",
     configDir: process.env.KIDS_OPENCODE_CONFIG_DIR ?? join(homedir(), ".config", "kids-opencode"),

package/src/core/events.ts

@@ -67,15 +67,23 @@ export class EventSubscriber {
   }
 
   private async consume(): Promise<void> {
-    // The SDK exposes the SSE stream via client.global.event(). Shape varies
-    // between SDK minor versions (some return async iterable, some a stream
-    // helper). We use the duck-typed iterable path.
-    const eventApi = (this.client as unknown as { global?: { event: () => AsyncIterable<unknown> } }).global
+    // The SDK exposes the SSE stream via client.global.event(). The shape
+    // has changed across SDK versions:
+    //   • old: event() returns an AsyncIterable directly
+    //   • new (>=1.14.51): event() returns Promise<{ stream: AsyncGenerator }>
+    // Handle both. The error "undefined is not a function (near '...raw of
+    // stream...')" came from `for await`-ing a Promise (the new shape) under
+    // the old code path.
+    const eventApi = (this.client as unknown as { global?: { event: (...a: unknown[]) => unknown } }).global
     if (!eventApi || typeof eventApi.event !== "function") {
       throw new Error("@opencode-ai/sdk/v2: client.global.event() not available — SDK version drift")
     }
-    const stream = eventApi.event()
-    for await (const raw of stream) {
+    const result = await Promise.resolve(eventApi.event())
+    const iterable = pickAsyncIterable(result)
+    if (!iterable) {
+      throw new Error(`@opencode-ai/sdk/v2: client.global.event() returned an unrecognised shape: ${describeShape(result)}`)
+    }
+    for await (const raw of iterable) {
       if (this.abort.signal.aborted) return
       if (this.retries > 0) {
         this.retries = 0
@@ -86,8 +94,19 @@ export class EventSubscriber {
   }
 
   private dispatch(raw: unknown): void {
-    const env = raw as { payload?: { type?: string } & Record<string, unknown> }
-    const payload = env?.payload
+    // Across SDK versions an event is either:
+    //   • { payload: { type, …fields } }            (older shape)
+    //   • { type, …fields }                          (newer shape — yielded
+    //                                                  directly by the
+    //                                                  AsyncGenerator)
+    //   • { data: { type, …fields } } (StreamEvent wrapper from some helpers)
+    // Unwrap to a single `payload` view so the switch below stays the same.
+    const e = raw as { payload?: Record<string, unknown>; data?: Record<string, unknown>; type?: string } & Record<string, unknown>
+    const payload: ({ type?: string } & Record<string, unknown>) | null =
+      (e?.payload && typeof e.payload === "object") ? (e.payload as { type?: string } & Record<string, unknown>)
+      : (e?.data && typeof e.data === "object" && typeof (e.data as { type?: unknown }).type === "string") ? (e.data as { type?: string } & Record<string, unknown>)
+      : (typeof e?.type === "string") ? (e as { type?: string } & Record<string, unknown>)
+      : null
     if (!payload || typeof payload.type !== "string") return
     const t = payload.type
     switch (t) {
@@ -166,3 +185,35 @@ function stringifyErr(err: unknown): string {
     return String(err)
   }
 }
+
+/**
+ * The SDK has shipped at least three event() return shapes over its 1.14.x
+ * line. Find the AsyncIterable in whichever shape we got, or null if none.
+ */
+function pickAsyncIterable(value: unknown): AsyncIterable<unknown> | null {
+  if (!value) return null
+  // Shape 1: the value IS the iterable.
+  if (typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === "function") {
+    return value as AsyncIterable<unknown>
+  }
+  // Shape 2: { stream: AsyncGenerator } — the >=1.14.51 ServerSentEventsResult.
+  const s = (value as { stream?: unknown }).stream
+  if (s && typeof (s as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === "function") {
+    return s as AsyncIterable<unknown>
+  }
+  // Shape 3: { data: { stream: ... } } — wrapped data envelope.
+  const d = (value as { data?: { stream?: unknown } }).data
+  if (d && typeof d === "object") {
+    const inner = (d as { stream?: unknown }).stream
+    if (inner && typeof (inner as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === "function") {
+      return inner as AsyncIterable<unknown>
+    }
+  }
+  return null
+}
+
+function describeShape(value: unknown): string {
+  if (value == null) return String(value)
+  if (typeof value !== "object") return typeof value
+  return `object keys=[${Object.keys(value as object).join(",")}]`
+}

package/src/core/setup.ts

@@ -80,7 +80,7 @@ export const PROVIDERS: ProviderChoice[] = [
   },
   {
     id: "openai",
-    label: "OpenAI GPT (ChatGPT Plus/Pro 可直接登录)",
+    label: "OpenAI GPT (sign in with ChatGPT Plus/Pro)",
     hint: "Already pay for ChatGPT Plus/Pro? Sign in with that — no API key. Otherwise pay-as-you-go ~$5-10/month.",
     envVar: "OPENAI_API_KEY",
     apiKeyUrl: "https://platform.openai.com/api-keys",

package/src/index.tsx

@@ -31,6 +31,7 @@ import { listInstalledPacks, resolveContext } from "./core/course-pack.ts"
 import { readLastSession, writeLastSession } from "./core/last-session.ts"
 import { isCompletionTrigger, runCheck } from "./core/check-runner.ts"
 import { App } from "./render/ink/App.tsx"
+import { FREE_PLAY_PACK_ID } from "./render/ink/screens/CoursePackPicker.tsx"
 import { detectDangerousTopicEn, detectDangerousTopicZh } from "./dangerous-topic-bridge.ts"
 import { OAUTH_HANDOFF_EXIT_CODE, saveSetup, saveSetupOauth, type ProviderId } from "./core/setup.ts"
 import { reloadEnvFile } from "./core/env-reload.ts"
@@ -73,6 +74,7 @@ interface AppHandlers {
   onPickerBack: () => void
   onMissionNext: () => void
   onMissionBack: () => void
+  onMissionExit: () => void
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
@@ -82,6 +84,25 @@ interface AppHandlers {
 }
 
 async function main(): Promise<void> {
+  // Switch to the terminal's alternate screen buffer so Ink draws on a
+  // canvas isolated from whatever was in the terminal before us — most
+  // importantly the green "Complete authorization…" lines printed by
+  // `opencode auth login` between two execs of kids-client. On exit, the
+  // kid's original terminal contents (incl. scrollback) come back.
+  //
+  // NOTE: do NOT install SIGINT/SIGTERM handlers here — the existing
+  // `process.on("SIGINT", () => void services.quit())` registration below
+  // is the cleanup owner; double-handling closed the raw-mode stdin out
+  // from under Ink and surfaced as "EIO on fd 8" when the kid pressed Esc.
+  // The "exit" listener alone is enough to restore the terminal for normal
+  // exits + the OAuth handoff `process.exit(OAUTH_HANDOFF_EXIT_CODE)`.
+  if (process.stdout.isTTY) {
+    process.stdout.write("\x1b[?1049h\x1b[H")
+    process.on("exit", () => {
+      try { process.stdout.write("\x1b[?1049l") } catch { /* terminal already closed */ }
+    })
+  }
+
   const env: KidsClientEnv = readEnv()
   const store = new Store()
   const installedPacks = listInstalledPacks()
@@ -209,6 +230,10 @@ function makeHandlers(
     onPickerBack: () => store.update({ screen: { kind: "startup" } }),
     onMissionNext: ifBooted((s) => s.handlers.onMissionNext()),
     onMissionBack: () => store.update({ screen: { kind: "mission" } }),
+    // Leave an in-progress mission and return to the startup menu. The serve +
+    // session keep running in the background; the kid just re-enters from the
+    // picker. Mirrors onHelpBack / onPickerBack.
+    onMissionExit: () => store.update({ screen: { kind: "startup" } }),
     onSetupSave: async (provider, apiKey) => {
       try {
         saveSetup({ configDir: env.configDir, provider, apiKey })
@@ -378,7 +403,17 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
       })
     },
     onDisconnected: (reason) => {
-      store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: reason } })
+      // This fires after the engine was already reachable, so the failure is a
+      // dropped event stream, not a failed startup. Make the detail say so —
+      // the variant's title still reads "AI teacher didn't start", but the
+      // detail keeps it from being misleading.
+      store.update({
+        screen: {
+          kind: "error",
+          variant: "serve_unreachable",
+          detail: `lost connection to the AI engine after it started — ${reason}`,
+        },
+      })
     },
     onReconnected: () => {
       flashToast(store, {
@@ -574,6 +609,12 @@ function makeFullHandlers(
       }
     },
     onPickPack: (packId) => {
+      if (packId === FREE_PLAY_PACK_ID) {
+        // Synthetic "I don't know yet — just chat" entry → free-play.
+        store.update({ coursePack: null, mission: null, packTitle: null, missionTitle: null, missionIndex: null, missionTotal: null })
+        store.update({ screen: { kind: "mission" } })
+        return
+      }
       store.update({ coursePack: packId, mission: null })
       refreshContext()
       store.update({ screen: { kind: "mission" } })

package/src/render/ink/App.tsx

@@ -57,6 +57,8 @@ export interface AppDeps {
   onPickerBack: () => void
   onMissionNext: () => void
   onMissionBack: () => void
+  /** Leave an in-progress mission and return to the startup menu. */
+  onMissionExit: () => void
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
@@ -105,9 +107,9 @@ export function App(deps: AppDeps): React.ReactElement {
     case "tour":
       return <TourScreen locale={deps.locale} onDone={deps.onTourDone} />
     case "startup":
-      return <StartupScreen locale={deps.locale} coursePack={state.coursePack} toast={state.toast} onStart={deps.onStart} onOpenWallet={deps.onOpenWallet} />
+      return <StartupScreen locale={deps.locale} coursePack={state.coursePack} toast={state.toast} onStart={deps.onStart} onOpenWallet={deps.onOpenWallet} onQuit={deps.onQuit} />
     case "mission":
-      return <MissionScreen state={state} locale={deps.locale} onPrompt={deps.onPrompt} onAbort={deps.onAbort} />
+      return <MissionScreen state={state} locale={deps.locale} onPrompt={deps.onPrompt} onAbort={deps.onAbort} onExit={deps.onMissionExit} />
     case "help":
       return <HelpScreen locale={deps.locale} onBack={deps.onHelpBack} />
     case "course_picker":

package/src/render/ink/components/Header.tsx

@@ -26,8 +26,17 @@ export function Header({ packTitle, missionTitle, missionIndex, missionTotal, st
     starsBudget > 0
       ? `⭐ ${starsBalance}/${starsBudget}`
       : `⭐ ${starsBalance}`
+  // borderStyle="round" + justifyContent="space-between" without an explicit
+  // width caused a cascade of stacked top-borders under Ink 5 + Bun — the
+  // Header re-rendered on every keystroke / spinner tick with a slightly
+  // different computed width, and Ink's diff failed to clear the old top
+  // border. Forcing width to the current terminal column count locks the
+  // measurement, and "single" border chars sidestep the rounded-corner
+  // width-counting glitch we hit in workshop dogfood (round corners stay
+  // available on Setup / Tour / Help screens which don't re-render rapidly).
+  const width = process.stdout.columns && process.stdout.columns > 4 ? process.stdout.columns : 80
   return (
-    <Box borderStyle="round" borderColor={theme.border} paddingX={1} justifyContent="space-between">
+    <Box borderStyle="single" borderColor={theme.border} paddingX={1} justifyContent="space-between" width={width}>
       <Text color={theme.accent}>{left}</Text>
       <Text color={theme.stars}>{stars}</Text>
     </Box>

package/src/render/ink/screens/CoursePackPicker.tsx

@@ -1,16 +1,21 @@
 /**
- * §3.1 [c] option — list installed Course Packs and let the kid pick one.
- * On selection, the parent transitions to MissionScreen with that pack
- * loaded.
+ * Project-type picker — first impression for a kid with no `--course` flag.
  *
- * Up / Down to move, Enter to select, Esc to go back.
+ * Lists installed packs (Game / Website / …) plus a synthetic "I don't know
+ * yet — just chat" entry that drops into free-play. Selection routes via the
+ * orchestrator's onPick callback; the magic `_free` id triggers free-play.
+ *
+ * Up / Down to move, Enter to select, Esc to go back to StartupScreen.
  */
 
-import React, { useState } from "react"
+import React, { useMemo, useState } from "react"
 import { Box, Text, useInput } from "ink"
 import { getTheme } from "../theme.ts"
 import type { InstalledPack } from "../../../core/course-pack.ts"
 
+/** Synthetic id reserved for the "just chat" entry; orchestrator maps this to free-play. */
+export const FREE_PLAY_PACK_ID = "_free"
+
 interface CoursePackPickerProps {
   locale: "zh-Hans" | "en"
   packs: InstalledPack[]
@@ -18,19 +23,32 @@ interface CoursePackPickerProps {
   onBack: () => void
 }
 
+interface PickerRow {
+  id: string
+  icon: string
+  label: string
+  description: string | null
+  /** Optional meta line ("3 missions · budget 40⭐") — null hides it. */
+  meta: string | null
+}
+
 export function CoursePackPicker({ locale, packs, onPick, onBack }: CoursePackPickerProps): React.ReactElement {
   const theme = getTheme()
+  const t = STRINGS[locale]
+  const rows: PickerRow[] = useMemo(() => buildRows(packs, t), [packs, t])
   const [idx, setIdx] = useState(0)
   useInput((_, key) => {
     if (key.escape) onBack()
     else if (key.upArrow) setIdx((i) => Math.max(0, i - 1))
-    else if (key.downArrow) setIdx((i) => Math.min(packs.length - 1, i + 1))
-    else if (key.return && packs[idx]) onPick(packs[idx]!.id)
+    else if (key.downArrow) setIdx((i) => Math.min(rows.length - 1, i + 1))
+    else if (key.return && rows[idx]) onPick(rows[idx]!.id)
   })
-  const t = STRINGS[locale]
-  if (packs.length === 0) {
+  const noRealPacks = packs.length === 0
+  if (noRealPacks) {
+    // Course Pack install is broken — surface it loudly, but still let the kid
+    // drop into free-play via the synthetic entry.
     return (
-      <Box flexDirection="column" borderStyle="round" borderColor={theme.warn} paddingX={2} paddingY={1}>
+      <Box flexDirection="column" borderStyle="single" borderColor={theme.warn} paddingX={2} paddingY={1} width={process.stdout.columns && process.stdout.columns > 4 ? process.stdout.columns : 80}>
         <Text color={theme.warn} bold>{t.empty}</Text>
         <Box marginTop={1}>
           <Text color={theme.fgDim}>{t.emptyHint}</Text>
@@ -42,20 +60,23 @@ export function CoursePackPicker({ locale, packs, onPick, onBack }: CoursePackPi
     )
   }
   return (
-    <Box flexDirection="column" borderStyle="round" borderColor={theme.accent} paddingX={2} paddingY={1}>
+    <Box flexDirection="column" borderStyle="single" borderColor={theme.accent} paddingX={2} paddingY={1} width={process.stdout.columns && process.stdout.columns > 4 ? process.stdout.columns : 80}>
       <Text color={theme.accent} bold>{t.title}</Text>
       <Box marginTop={1} flexDirection="column">
-        {packs.map((p, i) => {
+        {rows.map((row, i) => {
           const active = i === idx
           return (
-            <Box key={p.id} marginBottom={i === packs.length - 1 ? 0 : 0}>
+            <Box key={row.id}>
               <Text color={active ? theme.kid : theme.fg}>{active ? "▶ " : "  "}</Text>
+              <Text>{row.icon}{row.icon ? "  " : ""}</Text>
               <Box flexDirection="column" flexGrow={1}>
-                <Text color={active ? theme.accent : theme.fg} bold={active}>{p.title}</Text>
-                {p.shortDescription && (
-                  <Text color={theme.fgDim} dimColor={!active}>  {p.shortDescription}</Text>
+                <Text color={active ? theme.accent : theme.fg} bold={active}>{row.label}</Text>
+                {row.description && (
+                  <Text color={theme.fgDim} dimColor={!active}>  {row.description}</Text>
+                )}
+                {row.meta && (
+                  <Text color={theme.fgDim} dimColor>  {row.meta}</Text>
                 )}
-                <Text color={theme.fgDim} dimColor>  {t.meta(p.missionCount, p.starsBudget)}</Text>
               </Box>
             </Box>
           )
@@ -68,22 +89,50 @@ export function CoursePackPicker({ locale, packs, onPick, onBack }: CoursePackPi
   )
 }
 
+interface PickerStrings {
+  freePlayLabel: string
+  freePlayDescription: string
+  meta: (missions: number, stars: number) => string
+}
+
+function buildRows(packs: InstalledPack[], t: PickerStrings): PickerRow[] {
+  const rows: PickerRow[] = packs.map((p) => ({
+    id: p.id,
+    icon: p.icon ?? "📦",
+    label: p.pickerLabel ?? p.title,
+    description: p.shortDescription,
+    meta: p.missionCount > 0 ? t.meta(p.missionCount, p.starsBudget) : null,
+  }))
+  rows.push({
+    id: FREE_PLAY_PACK_ID,
+    icon: "🤔",
+    label: t.freePlayLabel,
+    description: t.freePlayDescription,
+    meta: null,
+  })
+  return rows
+}
+
 const STRINGS = {
   "zh-Hans": {
-    title: "选一个 Course Pack",
+    title: "你好呀. 今天想做点啥?",
     empty: "还没装任何 Course Pack",
     emptyHint: "Course Pack 是 Airbotix 老师做的引导式项目。请家长重新装 kids-opencode 把它带回来。",
     backHint: "[Esc / Enter] 返回",
     hints: "[↑↓] 选 · [Enter] 确认 · [Esc] 返回",
+    freePlayLabel: "还没想好 — 聊聊看",
+    freePlayDescription: "先跟 AI 聊一聊，再决定做啥也行。",
     meta: (missions: number, stars: number) =>
       stars > 0 ? `${missions} 个 Mission · 预算 ${stars}⭐` : `${missions} 个 Mission`,
   },
   en: {
-    title: "Pick a Course Pack",
+    title: "Welcome, friend. What do you want to make today?",
     empty: "No Course Packs installed yet",
     emptyHint: "Course Packs are guided projects from Airbotix. Ask a grown-up to reinstall kids-opencode.",
     backHint: "[Esc / Enter] Back",
     hints: "[↑↓] move · [Enter] choose · [Esc] back",
+    freePlayLabel: "I don't know yet — just chat",
+    freePlayDescription: "Talk to the AI first, then decide what to make.",
     meta: (missions: number, stars: number) =>
       stars > 0 ? `${missions} missions · budget ${stars}⭐` : `${missions} missions`,
   },

package/src/render/ink/screens/MissionScreen.tsx

@@ -24,20 +24,29 @@ interface MissionScreenProps {
   locale: "zh-Hans" | "en"
   onPrompt: (text: string) => void
   onAbort: () => void
+  /** Leave the mission and return to the startup menu. */
+  onExit: () => void
 }
 
-export function MissionScreen({ state, locale, onPrompt, onAbort }: MissionScreenProps): React.ReactElement {
+export function MissionScreen({ state, locale, onPrompt, onAbort, onExit }: MissionScreenProps): React.ReactElement {
   const theme = getTheme()
   const [draft, setDraft] = useState("")
   const placeholder = locale === "zh-Hans" ? "想做什么？告诉我吧（中文/英文都行）" : "What would you like to make? (English or Chinese)"
 
+  // Esc is overloaded so it never eats the kid's typing: while the AI is
+  // thinking it interrupts; with text typed it clears the draft; when idle and
+  // empty it leaves the mission back to the startup menu (so the kid isn't
+  // trapped here — dogfood feedback).
   useInput((_, key) => {
-    if (key.escape && state.thinking) onAbort()
+    if (!key.escape) return
+    if (state.thinking) onAbort()
+    else if (draft.length > 0) setDraft("")
+    else onExit()
   })
 
   const hint = locale === "zh-Hans"
-    ? "提示：做完一关时打 /check 或「我做完了」就能验收 · 按 Esc 打断 AI"
-    : "Tip: type /check or 'I'm done' to validate · Esc interrupts the AI"
+    ? "提示：做完一关时打 /check 或「我做完了」就能验收 · 按 Esc 打断 AI / 返回菜单"
+    : "Tip: type /check or 'I'm done' to validate · Esc interrupts the AI / returns to menu"
 
   return (
     <Box flexDirection="column">

package/src/render/ink/screens/StartupScreen.tsx

@@ -2,11 +2,14 @@
  * §3.1 Startup screen — first impression. Must paint within 5s.
  *
  * Quick keys:
- *   Enter → start a free-play session OR continue if a course pack is set
- *   c     → choose a Course Pack
+ *   Enter → if a Course Pack is preselected (via --course): continue.
+ *           Otherwise: open the project-type picker.
+ *   c     → open the project-type picker explicitly
+ *   f     → start a free-play session (no Course Pack)
  *   r     → resume the last session
  *   w     → open Airbotix Portal wallet / login in the parent's browser
  *   h     → show kid-friendly help
+ *   q     → quit Kids OpenCode
  */
 
 import React from "react"
@@ -22,16 +25,19 @@ interface StartupScreenProps {
   toast: ToastState | null
   onStart: (mode: "free" | "course" | "resume" | "help") => void
   onOpenWallet: () => void
+  onQuit: () => void
 }
 
-export function StartupScreen({ locale, coursePack, toast, onStart, onOpenWallet }: StartupScreenProps): React.ReactElement {
+export function StartupScreen({ locale, coursePack, toast, onStart, onOpenWallet, onQuit }: StartupScreenProps): React.ReactElement {
   const theme = getTheme()
   useInput((input, key) => {
-    if (key.return) onStart(coursePack ? "course" : "free")
+    if (key.return) onStart("course")
     else if (input === "c") onStart("course")
+    else if (input === "f") onStart("free")
     else if (input === "r") onStart("resume")
     else if (input === "w" || input === "W") onOpenWallet()
     else if (input === "h") onStart("help")
+    else if (input === "q" || input === "Q") onQuit()
   })
   const t = STRINGS[locale]
   return (
@@ -53,11 +59,13 @@ export function StartupScreen({ locale, coursePack, toast, onStart, onOpenWallet
       </Box>
       <Box marginTop={2}>
         <KeyHints hints={[
-          { key: "Enter", label: coursePack ? t.startCourse : t.startFree },
-          { key: "c", label: t.pickCourse },
+          { key: "Enter", label: coursePack ? t.startCourse : t.pickCourse },
+          ...(coursePack ? [{ key: "c", label: t.pickCourse }] : []),
+          { key: "f", label: t.startFree },
           { key: "r", label: t.resume },
           { key: "w", label: t.wallet },
           { key: "h", label: t.help },
+          { key: "q", label: t.quit },
         ]} />
       </Box>
       {toast && (
@@ -83,6 +91,7 @@ const STRINGS = {
     resume: "继续上次",
     wallet: "钱包 / 充值（开浏览器）",
     help: "帮助",
+    quit: "退出",
   },
   en: {
     tagline: "🤖  Your AI coding buddy  🤖",
@@ -97,5 +106,6 @@ const STRINGS = {
     resume: "Resume last session",
     wallet: "Wallet / Top up (opens browser)",
     help: "Help",
+    quit: "Quit",
   },
 } as const

package/src/render/ink/theme.ts

@@ -36,9 +36,13 @@ export interface Theme {
 
 /** Default — vibrant on a dark terminal. */
 const DARK: Theme = {
-  fg: "white",
+  // Primary text is bright white and secondary text is plain white (not
+  // "gray"/blackBright, which renders near-invisible on many dark themes) so
+  // body copy actually reads. The fg/fgDim pair still differ enough to mark
+  // hierarchy. See dogfood feedback: "can't see the text, not prominent".
+  fg: "whiteBright",
   bg: "black",
-  fgDim: "gray",
+  fgDim: "white",
   accent: "yellow",
   warn: "yellow",
   danger: "red",