@kidsinai/kids-client 0.0.11 → 0.0.16

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.11",
+  "version": "0.0.16",
   "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.16"
   },
   "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`. */
@@ -37,6 +41,12 @@ export interface KidsClientEnv {
   configDir: string
   /** When true, the client renders a "Tony banner" / suppresses interactive prompts (CI). */
   noBanner: boolean
+  /**
+   * Airbotix Portal base URL — used by the [w] Wallet / Top-up shortcut to
+   * deep-link parents into login + Airwallex top-up. Defaults to
+   * https://app.airbotix.ai; staging overrides via AIRBOTIX_PORTAL_URL.
+   */
+  portalBaseUrl: string
 }
 
 export function readEnv(): KidsClientEnv {
@@ -51,10 +61,13 @@ 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"),
     noBanner: process.env.KIDS_OPENCODE_NO_BANNER === "1",
+    portalBaseUrl: process.env.AIRBOTIX_PORTAL_URL || "https://app.airbotix.ai",
   }
 }
 

package/src/core/wallet-link.ts

@@ -0,0 +1,76 @@
+/**
+ * Wallet / login deep-link to Airbotix Portal.
+ *
+ * V0 strategy: open the parent's default browser to portal/wallet?from=cli.
+ * Portal handles auth (login first if no session) and Airwallex hosted card
+ * entry. TUI does not touch card data — PCI scope stays in the browser.
+ *
+ * A stable device-id (random UUID, persisted under configDir) is included
+ * so platform-backend can later correlate top-ups with the local install
+ * for V1 device-link polling. Today portal just logs it.
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { randomUUID } from "node:crypto"
+
+export const DEFAULT_PORTAL_BASE_URL = "https://app.airbotix.ai"
+
+export function getOrCreateDeviceId(configDir: string): string {
+  const p = join(configDir, "device-id")
+  if (existsSync(p)) {
+    const v = readFileSync(p, "utf8").trim()
+    if (v) return v
+  }
+  mkdirSync(configDir, { recursive: true })
+  const id = randomUUID()
+  writeFileSync(p, id + "\n", { mode: 0o600 })
+  return id
+}
+
+export interface WalletUrlOpts {
+  portalBaseUrl?: string
+  deviceId: string
+  locale?: "zh-Hans" | "en"
+}
+
+export function buildWalletUrl(opts: WalletUrlOpts): string {
+  const base = (opts.portalBaseUrl || DEFAULT_PORTAL_BASE_URL).replace(/\/+$/, "")
+  const params = new URLSearchParams({
+    from: "cli",
+    device: opts.deviceId,
+  })
+  if (opts.locale) params.set("lang", opts.locale)
+  return `${base}/portal/wallet?${params.toString()}`
+}
+
+export type OpenResult = { ok: true } | { ok: false; reason: string }
+
+export function openInBrowser(url: string): OpenResult {
+  const platform = process.platform
+  let cmd: string
+  let args: string[]
+  if (platform === "darwin") {
+    cmd = "open"
+    args = [url]
+  } else if (platform === "win32") {
+    // `start` is a cmd.exe builtin; the empty "" is the window title slot.
+    cmd = "cmd"
+    args = ["/c", "start", "", url]
+  } else {
+    cmd = "xdg-open"
+    args = [url]
+  }
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" })
+    child.on("error", () => {
+      // Swallow async spawn errors — TUI already showed a toast saying we
+      // tried, and the parent can copy the URL from the toast as fallback.
+    })
+    child.unref()
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/index.tsx

@@ -31,12 +31,14 @@ 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"
 import { hasSeenTour, markTourSeen } from "./core/tour-marker.ts"
 import type { InstalledPack } from "./core/course-pack.ts"
 import { loadCoursePack } from "@kidsinai/kids-opencode-plugin"
+import { buildWalletUrl, getOrCreateDeviceId, openInBrowser } from "./core/wallet-link.ts"
 
 interface ServiceSet {
   audit: AuditPipeline
@@ -77,6 +79,7 @@ interface AppHandlers {
   onSetupSkip: () => void
   onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
   onTourDone: () => void
+  onOpenWallet: () => void
 }
 
 async function main(): Promise<void> {
@@ -248,6 +251,25 @@ function makeHandlers(
       const r = getResolveTour()
       if (r) r()
     },
+    onOpenWallet: () => {
+      const deviceId = getOrCreateDeviceId(env.configDir)
+      const url = buildWalletUrl({
+        portalBaseUrl: env.portalBaseUrl,
+        deviceId,
+        locale: env.locale,
+      })
+      const result = openInBrowser(url)
+      const okText = env.locale === "zh-Hans"
+        ? `已在浏览器打开：${url}`
+        : `Opened in your browser: ${url}`
+      const failText = env.locale === "zh-Hans"
+        ? `没办法自动开浏览器。请手动打开：${url}`
+        : `Couldn't auto-open the browser. Open manually: ${url}`
+      flashToast(store, {
+        kind: result.ok ? "success" : "warn",
+        text: result.ok ? okText : failText,
+      })
+    },
   }
 }
 
@@ -553,6 +575,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

@@ -62,6 +62,13 @@ export interface AppDeps {
   onSetupSkip: () => void
   onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
   onTourDone: () => void
+  /**
+   * Open the Airbotix Portal wallet/login page in the parent's default
+   * browser. Wired into [w] on StartupScreen and into the
+   * `stars_exhausted` ErrorScreen so parents can top up without
+   * remembering the URL.
+   */
+  onOpenWallet: () => void
 }
 
 export function App(deps: AppDeps): React.ReactElement {
@@ -98,7 +105,7 @@ 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} onStart={deps.onStart} />
+      return <StartupScreen locale={deps.locale} coursePack={state.coursePack} toast={state.toast} onStart={deps.onStart} onOpenWallet={deps.onOpenWallet} />
     case "mission":
       return <MissionScreen state={state} locale={deps.locale} onPrompt={deps.onPrompt} onAbort={deps.onAbort} />
     case "help":
@@ -132,8 +139,10 @@ export function App(deps: AppDeps): React.ReactElement {
           variant={state.screen.variant}
           detail={state.screen.detail}
           locale={deps.locale}
+          toast={state.toast}
           onRetry={deps.onErrorRetry}
           onReconfigure={RECONFIGURABLE_VARIANTS.has(state.screen.variant) ? deps.onReconfigure : undefined}
+          onOpenWallet={state.screen.variant === "stars_exhausted" ? deps.onOpenWallet : undefined}
           onQuit={deps.onQuit}
         />
       )

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,17 +23,30 @@ 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}>
         <Text color={theme.warn} bold>{t.empty}</Text>
@@ -45,17 +63,20 @@ export function CoursePackPicker({ locale, packs, onPick, onBack }: CoursePackPi
     <Box flexDirection="column" borderStyle="round" borderColor={theme.accent} paddingX={2} paddingY={1}>
       <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/ErrorScreen.tsx

@@ -14,11 +14,13 @@ import React from "react"
 import { Box, Text, useInput } from "ink"
 import { getTheme } from "../theme.ts"
 import type { ErrorVariant } from "../../../core/store.ts"
+import { Toast, type ToastState } from "../components/Toast.tsx"
 
 interface ErrorScreenProps {
   variant: ErrorVariant
   locale: "zh-Hans" | "en"
   detail?: string
+  toast?: ToastState | null
   onRetry?: () => void
   onQuit?: () => void
   /**
@@ -28,13 +30,20 @@ interface ErrorScreenProps {
    * alone won't fix a wrong key.
    */
   onReconfigure?: () => void
+  /**
+   * Open the Airbotix Portal wallet page in the parent's default browser.
+   * Wired only for `stars_exhausted` so retry-alone (which won't change the
+   * balance) is not the only option.
+   */
+  onOpenWallet?: () => void
 }
 
-export function ErrorScreen({ variant, locale, detail, onRetry, onQuit, onReconfigure }: ErrorScreenProps): React.ReactElement {
+export function ErrorScreen({ variant, locale, detail, toast, onRetry, onQuit, onReconfigure, onOpenWallet }: ErrorScreenProps): React.ReactElement {
   const theme = getTheme()
   useInput((input, key) => {
     if (key.return && onRetry) onRetry()
     else if ((input === "c" || input === "C") && onReconfigure) onReconfigure()
+    else if ((input === "w" || input === "W") && onOpenWallet) onOpenWallet()
     else if (input === "q" && onQuit) onQuit()
   })
   const t = STRINGS[locale][variant]
@@ -66,6 +75,12 @@ export function ErrorScreen({ variant, locale, detail, onRetry, onQuit, onReconf
             <Text color={theme.fg}> {STRINGS[locale].reconfigure}</Text>
           </Box>
         )}
+        {onOpenWallet && (
+          <Box marginRight={2}>
+            <Text color={theme.accent}>[w]</Text>
+            <Text color={theme.fg}> {STRINGS[locale].topUp}</Text>
+          </Box>
+        )}
         {onQuit && (
           <Box>
             <Text color={theme.accent}>[q]</Text>
@@ -73,6 +88,11 @@ export function ErrorScreen({ variant, locale, detail, onRetry, onQuit, onReconf
           </Box>
         )}
       </Box>
+      {toast && (
+        <Box marginTop={1}>
+          <Toast toast={toast} />
+        </Box>
+      )}
     </Box>
   )
 }
@@ -81,6 +101,7 @@ const STRINGS = {
   "zh-Hans": {
     quit: "退出",
     reconfigure: "改设置（换 key / 换 provider）",
+    topUp: "去充值（开浏览器）",
     serve_unreachable: {
       title: "AI 老师还没起来",
       body: "后台 AI 服务好像没启动。要不要再试一次？",
@@ -98,7 +119,7 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "今天的 ⭐ 用完了",
-      body: "今天先到这里啦！\n你做得很好，我们明天接着来。\n或者找家长打开 airbotix.ai/portal/wallet 多充一点 ⭐，然后按 Enter 接着做。",
+      body: "今天先到这里啦！\n你做得很好，我们明天接着来。\n或者按 [w] 让家长去充值，回来按 Enter 接着做。",
       retry: "找完家长了，再试一次",
     },
     auth_failed: {
@@ -120,6 +141,7 @@ const STRINGS = {
   en: {
     quit: "Quit",
     reconfigure: "Change settings (switch key / provider)",
+    topUp: "Top up (opens browser)",
     serve_unreachable: {
       title: "AI teacher didn't start",
       body: "The background AI service isn't running. Try again?",
@@ -137,7 +159,7 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "Out of ⭐ for today",
-      body: "Great work today!\nWe'll pick this up tomorrow.\nOr ask a parent to top up at airbotix.ai/portal/wallet, then press Enter to keep going.",
+      body: "Great work today!\nWe'll pick this up tomorrow.\nOr press [w] so a parent can top up, then press Enter to keep going.",
       retry: "Asked a parent — try again",
     },
     auth_failed: {

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

@@ -2,9 +2,12 @@
  * §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
  */
 
@@ -13,19 +16,24 @@ import { Box, Text, useInput } from "ink"
 import { getTheme } from "../theme.ts"
 import { KidsLogo } from "../components/KidsLogo.tsx"
 import { KeyHints } from "../components/KeyHints.tsx"
+import { Toast, type ToastState } from "../components/Toast.tsx"
 
 interface StartupScreenProps {
   locale: "zh-Hans" | "en"
   coursePack: string | null
+  toast: ToastState | null
   onStart: (mode: "free" | "course" | "resume" | "help") => void
+  onOpenWallet: () => void
 }
 
-export function StartupScreen({ locale, coursePack, onStart }: StartupScreenProps): React.ReactElement {
+export function StartupScreen({ locale, coursePack, toast, onStart, onOpenWallet }: 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")
   })
   const t = STRINGS[locale]
@@ -48,12 +56,19 @@ export function StartupScreen({ locale, coursePack, onStart }: StartupScreenProp
       </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 },
         ]} />
       </Box>
+      {toast && (
+        <Box marginTop={1}>
+          <Toast toast={toast} />
+        </Box>
+      )}
     </Box>
   )
 }
@@ -70,6 +85,7 @@ const STRINGS = {
     startCourse: "继续 Course Pack",
     pickCourse: "选 Course Pack",
     resume: "继续上次",
+    wallet: "钱包 / 充值（开浏览器）",
     help: "帮助",
   },
   en: {
@@ -83,6 +99,7 @@ const STRINGS = {
     startCourse: "Continue Course Pack",
     pickCourse: "Pick a Course Pack",
     resume: "Resume last session",
+    wallet: "Wallet / Top up (opens browser)",
     help: "Help",
   },
 } as const