@forgeax/interface 0.4.1

package/dist/package/node/components/Onboarding/OnboardingController.js

@@ -0,0 +1,549 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// OnboardingController — faithful port of first-run-onboarding-prototype onto
+// the live shell (design §11). Phases:
+//
+//   welcome  → language + connect-a-model (mutually exclusive API Key / local CLI;
+//              Next probes the selected path) → 2s auto-advance on success.
+//   project  → root dir + new / open / sample project cards → enter home.
+//   home     → TourOverlay coach marks over the LIVE shell, then a first-chat
+//              nudge near the composer. Completing / skipping ends onboarding.
+//
+// Runtime state (open sub-modal, check result, countdown) is ephemeral; only
+// the phase + milestone flags persist (Onboarding/types).
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createIntervalTaskLifecycle } from '@forgeax/app-shell/react';
+import { useTranslation, changeLanguage, getLocale } from '../../i18n/index.js';
+import { getStudioProjectClient, useShellStore } from '../../store.js';
+import { useHost } from '../../core/app-shell/index.js';
+import { applyModelRoute } from '../../lib/model-route/index.js';
+import { listModelsWithLive } from '../../lib/model-config.js';
+import { fetchCliProviders } from '../../lib/cli-providers.js';
+import { FsBrowser } from '../TopBar/FsBrowser.js';
+
+// FsBrowser's footer buttons are .tb-modal-btn — declare that dependency here
+// instead of inheriting it from TopBar, which is unmounted during onboarding.
+
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select.js';
+import { TourOverlay } from '../TourOverlay/index.js';
+import { APP_EVENTS } from '../../lib/storageKeys.js';
+import { resolveHomeOnboarding, shouldActivateTour } from './home-transition.js';
+import { loadOnboarding, saveOnboarding, PHASE_ORDER } from './types.js';
+import { interpretLiveCatalogProbe, needsConnectSelection, validateApiKeyFields, } from './connect-selection.js';
+import { isUserExistingGame, resolveProjectName, toGameSlug } from './project-name.js';
+import { latchTourShellDefaults, prepareTourShell } from './prepareTourShell.js';
+import { listGameTemplates } from '../../lib/game-templates.js';
+
+/** Map raw server errors to onboarding copy (keep unknown messages as-is). */
+function formatProjectError(raw, t) {
+    if (/not a game folder/i.test(raw))
+        return t('onboarding.project.errNotGame');
+    return raw;
+}
+// Install-doc links, keyed by driver id. Optional lookup: a driver reported by
+// /api/cli/health but absent here simply renders without a "how to install" link.
+const CLI_LINKS = {
+    'claude-code': { name: 'Claude Code', url: 'https://code.claude.com/docs/en/setup' },
+    codex: { name: 'Codex CLI', url: 'https://developers.openai.com/codex/quickstart' },
+    'cursor-agent': { name: 'Cursor CLI', url: 'https://cursor.com/docs/cli/installation' },
+    codebuddy: { name: 'CodeBuddy CLI', url: 'https://www.codebuddy.ai/cli' },
+    'kimi-code': { name: 'Kimi Code CLI', url: 'https://www.kimi.com/code/docs/kimi-code-cli/guides/getting-started.html' },
+    'deepseek-harness': { name: 'DeepSeek Harness', url: 'https://github.com/deepseek-ai/deepseek-harness' },
+};
+// The native ForgeaX kernel (forgeax-core / forgeax) is registered in the shared
+// kernel registry, so /api/cli/health surfaces it too — but it is NOT a
+// connectable "Local CLI" (it's the API-key native path). Mirror
+// Settings › Providers and drop it from the Local CLI dropdown.
+const NATIVE_KERNEL_IDS = new Set(['forgeax-core', 'forgeax']);
+// Seed list painted INSTANTLY (before /api/cli/health resolves) so all rows show
+// up immediately in a "checking…" state rather than an empty box. It must be the
+// COMPLETE known driver set (incl. codebuddy) — an incomplete seed was the "3 now,
+// codebuddy later" bug. It is only a paint-fast optimism: once health returns it
+// becomes the source of truth (below), so a future driver it doesn't list still
+// appears, and per-row status is always live.
+const SEED_CLI_IDS = ['claude-code', 'codex', 'cursor-agent', 'codebuddy', 'kimi-code', 'deepseek-harness'];
+/** Local-CLI driver ids to offer. Before health lands: the complete seed (all
+ *  rows visible, each "checking"). After: derived LIVE from /api/cli/health with
+ *  the native path dropped — authoritative, so drivers can be added/removed and
+ *  each row's dot reflects real reachability. */
+function cliIdsFrom(providers) {
+    if (!providers)
+        return SEED_CLI_IDS;
+    return providers.filter((p) => !NATIVE_KERNEL_IDS.has(p.id)).map((p) => p.id);
+}
+// Fallback model pinned when the user activates the API-key source in onboarding
+// without a finer choice — mirrors Settings › Providers (SectionsRegister's
+// `apiModel` fallback) so the active-source derivation resolves to 'api-key'
+// and the native path has a concrete model to call.
+const OB_API_KEY_DEFAULT_MODEL = 'gpt-4o-mini';
+const CLI_STATUS_COLOR = {
+    loading: 'var(--ob-text-3)',
+    ok: 'var(--ob-ok, #3fa266)',
+    down: 'var(--ob-err, #e04a5a)',
+    unknown: 'var(--ob-text-3)',
+};
+/** Map a CLI id against live health into a connectable-status token. */
+function cliStatus(id, providers) {
+    if (!providers)
+        return 'loading';
+    const found = providers.find((p) => p.id === id);
+    if (!found)
+        return 'unknown'; // not reported by /api/cli/health → not installed
+    return found.health.ok ? 'ok' : 'down';
+}
+/** Dropdown option: id + a colored status dot + a "connectable" label, so the
+ *  user can tell which local CLI is actually usable before picking it. */
+function CliOptionLabel({ t, id, providers }) {
+    const kind = cliStatus(id, providers);
+    // Prefer the health-reported display name (e.g. "CodeBuddy CLI"), then the
+    // install-doc table, then the raw id — so the row reads human, not slug.
+    const label = providers?.find((p) => p.id === id)?.displayName ?? CLI_LINKS[id]?.name ?? id;
+    return (_jsxs("span", { style: { display: 'inline-flex', alignItems: 'center', gap: 8 }, children: [_jsx("span", { style: { width: 7, height: 7, borderRadius: '50%', background: CLI_STATUS_COLOR[kind], flexShrink: 0 } }), _jsx("span", { children: label }), _jsx("span", { className: "fx-ob-tiny fx-ob-muted", children: t(`onboarding.connect.cliStatus.${kind}`) })] }));
+}
+async function patchEnv(patch) {
+    const r = await fetch('/api/settings/env', {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(patch),
+    });
+    const j = (await r.json().catch(() => null));
+    if (!r.ok || !j?.ok)
+        throw new Error(j?.error ?? `HTTP ${r.status}`);
+}
+export function OnboardingController({ tourEnabled = true } = {}) {
+    const { t } = useTranslation();
+    const host = useHost();
+    const openOverlay = useShellStore((s) => s.openOverlay);
+    const setActiveGame = useShellStore((s) => s.setActiveGame);
+    const [phase, setPhaseState] = useState(() => loadOnboarding().phase);
+    const [lang, setLang] = useState(() => getLocale());
+    // ── welcome: connect-a-model runtime ──
+    const [selected, setSelected] = useState(null);
+    const [baseUrl, setBaseUrl] = useState('');
+    const [apiKey, setApiKey] = useState('');
+    const [cli, setCli] = useState('claude-code');
+    // Live health of local CLI drivers, keyed by provider id — drives the
+    // per-option "connectable" status inside the CLI dropdown. Fetched lazily the
+    // first time the CLI section is expanded (the endpoint live-checks each CLI).
+    const [cliProviders, setCliProviders] = useState(null);
+    const [checking, setChecking] = useState(false);
+    const [checkResult, setCheckResult] = useState('');
+    const [checkFailMsg, setCheckFailMsg] = useState('');
+    const [countdown, setCountdown] = useState(null);
+    const cdRef = useRef(null);
+    // ── project runtime: project = one game directory ──
+    const [projName, setProjName] = useState('');
+    const [fsOpen, setFsOpen] = useState(false);
+    const [tmplOpen, setTmplOpen] = useState(false);
+    const [templates, setTemplates] = useState(null);
+    const [tmplSlug, setTmplSlug] = useState(null);
+    const [projBusy, setProjBusy] = useState(false);
+    // Which action is in-flight — drives a specific "creating…/copying…/opening…"
+    // loading banner so the (possibly multi-second) server-side copy isn't a
+    // silent freeze followed by an abrupt jump to home.
+    const [projBusyKind, setProjBusyKind] = useState(null);
+    const [projErr, setProjErr] = useState(null);
+    // ── home runtime ──
+    // Resume from persisted milestones: a returning user who already finished the
+    // tour must NOT see it again on reload. The first-chat hint now lives in the
+    // chat empty state (ChatPanel), not here.
+    const [tourIdx, setTourIdx] = useState(0);
+    const [tourActive, setTourActive] = useState(() => shouldActivateTour(tourEnabled, loadOnboarding()));
+    // Open the real Level Page so tour anchors (sidebar/viewport/chat) exist.
+    useEffect(() => {
+        if (phase !== 'home' || !tourActive)
+            return;
+        prepareTourShell(host);
+    }, [phase, tourActive, host]);
+    const setPhase = useCallback((p) => {
+        setPhaseState(p);
+        const prev = loadOnboarding();
+        saveOnboarding({ ...prev, phase: p });
+        // Notify the shell gate (App.useOnboardingPhase) so it can mount/unmount the
+        // full shell as we move between init (welcome/project) and layout (home).
+        window.dispatchEvent(new CustomEvent(APP_EVENTS.onboardingChanged));
+    }, []);
+    // Repair persisted `home` states left by older IDE builds that disabled the
+    // tour without completing the state machine. The initialization policy above
+    // suppresses the overlay in memory even when persistence is unavailable.
+    useEffect(() => {
+        if (phase !== 'home' || tourEnabled)
+            return;
+        const transition = resolveHomeOnboarding(loadOnboarding(), false);
+        setTourActive(false);
+        saveOnboarding(transition.state);
+        setPhaseState(transition.state.phase);
+        window.dispatchEvent(new CustomEvent(APP_EVENTS.onboardingChanged));
+    }, [phase, tourEnabled]);
+    const clearCountdown = () => {
+        const countdown = cdRef.current;
+        cdRef.current = null;
+        countdown?.dispose();
+    };
+    const resetCheck = useCallback(() => {
+        clearCountdown();
+        setChecking(false);
+        setCheckResult('');
+        setCheckFailMsg('');
+        setCountdown(null);
+    }, []);
+    useEffect(() => () => clearCountdown(), []);
+    // Prefetch local CLI health on mount (NOT lazily on card-open): the probe
+    // live-checks every driver binary and takes a few seconds, so firing it while
+    // the user is still reading the welcome screen means the dropdown is already
+    // correct + complete (incl. codebuddy) by the time they expand the CLI card —
+    // no stale-then-mutate flash.
+    useEffect(() => {
+        if (cliProviders)
+            return;
+        let cancelled = false;
+        fetchCliProviders()
+            .then(({ providers }) => {
+            if (cancelled)
+                return;
+            setCliProviders(providers);
+            // Correct the default selection once the live set is known: if the
+            // preset (claude-code) isn't among the connectable drivers this
+            // machine reports, fall back to the first one so the dropdown never
+            // shows a value that has no option row.
+            const ids = cliIdsFrom(providers);
+            if (ids.length > 0 && !ids.includes(cli))
+                setCli(ids[0]);
+        })
+            .catch(() => { if (!cancelled)
+            setCliProviders([]); });
+        return () => { cancelled = true; };
+    }, [cliProviders, cli]);
+    const connectedList = useCallback(() => {
+        if (selected === 'key')
+            return [t('onboarding.connected.key')];
+        if (selected === 'cli')
+            return [t('onboarding.connected.cli', { cli })];
+        return [];
+    }, [selected, cli, t]);
+    const beginCountdown = useCallback(() => {
+        setCountdown(2);
+        const countdown = createIntervalTaskLifecycle({
+            intervalMs: 1000,
+            task: () => {
+                setCountdown((c) => {
+                    if (c === null)
+                        return null;
+                    if (c <= 1) {
+                        clearCountdown();
+                        resetCheck();
+                        setPhase('project');
+                        return null;
+                    }
+                    return c - 1;
+                });
+            },
+        });
+        cdRef.current = countdown;
+        countdown.start();
+    }, [resetCheck, setPhase]);
+    const runCheck = useCallback(async () => {
+        if (needsConnectSelection(selected)) {
+            setChecking(false);
+            setCheckResult('fail');
+            setCheckFailMsg(t('onboarding.check.failNeedSelect'));
+            return;
+        }
+        resetCheck();
+        setChecking(true);
+        try {
+            if (selected === 'key') {
+                if (validateApiKeyFields(baseUrl, apiKey) === 'empty') {
+                    setChecking(false);
+                    setCheckResult('fail');
+                    setCheckFailMsg(t('onboarding.check.failEmpty'));
+                    return;
+                }
+                const url = baseUrl.trim();
+                const key = apiKey.trim();
+                // Align with Settings › Providers: live catalog + llm-gateway read
+                // LITELLM_PROXY_*, and forgeax-core speaks Anthropic protocol against
+                // ANTHROPIC_* (mirrored on save). OPENAI_* still set for gpt-* routing.
+                await patchEnv({
+                    OPENAI_BASE_URL: url,
+                    OPENAI_API_KEY: key,
+                    LITELLM_PROXY_BASE_URL: url,
+                    LITELLM_PROXY_KEY: key,
+                    ANTHROPIC_BASE_URL: url,
+                    ANTHROPIC_API_KEY: key,
+                });
+                // Gate on LIVE /v1/models only — list_models falls back to disk catalog
+                // when live fails, so a bare listModels() would always "succeed".
+                const { live } = await listModelsWithLive(null);
+                const probe = interpretLiveCatalogProbe(live);
+                if (!probe.ok) {
+                    setChecking(false);
+                    setCheckResult('fail');
+                    setCheckFailMsg(t('onboarding.check.failLive'));
+                    return;
+                }
+                try {
+                    const { refreshAllModelCatalogs } = await import('../ModelPicker/useModelCatalog.js');
+                    await refreshAllModelCatalogs();
+                }
+                catch { /* best-effort UI cache refresh */ }
+                await applyModelRoute({ kind: 'api-key', model: OB_API_KEY_DEFAULT_MODEL });
+                setChecking(false);
+                setCheckResult('ok');
+                beginCountdown();
+                return;
+            }
+            // selected === 'cli'
+            let ok = false;
+            try {
+                const { providers } = await fetchCliProviders(true);
+                ok = !!providers.find((p) => p.id === cli)?.health.ok;
+            }
+            catch {
+                ok = false;
+            }
+            if (ok) {
+                await applyModelRoute({ kind: 'cli', providerId: cli });
+                setChecking(false);
+                setCheckResult('ok');
+                beginCountdown();
+            }
+            else {
+                setChecking(false);
+                setCheckResult('fail');
+                const lk = CLI_LINKS[cli];
+                setCheckFailMsg(lk ? (_jsxs(_Fragment, { children: [t('onboarding.check.failCli', { cli }), ' ', _jsx("a", { href: lk.url, target: "_blank", rel: "noopener noreferrer", children: lk.name })] })) : (t('onboarding.check.failCli', { cli })));
+            }
+        }
+        catch (e) {
+            setChecking(false);
+            setCheckResult('fail');
+            setCheckFailMsg(e.message || t('onboarding.check.fail'));
+        }
+    }, [selected, resetCheck, baseUrl, apiKey, cli, beginCountdown, t]);
+    // §14: there is NO "skip to home" — layout (home) is entered ONLY after a
+    // project is initialized (createGame / openGameDir → enterHomeWith). The
+    // welcome step's "skip" only skips model-connect and lands on `project`.
+    const skipConnect = useCallback(() => { resetCheck(); setPhase('project'); }, [resetCheck, setPhase]);
+    // Lazily load the built-in templates the first time the template modal opens.
+    useEffect(() => {
+        if (!tmplOpen || templates)
+            return;
+        let cancelled = false;
+        void listGameTemplates()
+            .then((items) => { if (!cancelled)
+            setTemplates(items); })
+            .catch(() => { if (!cancelled)
+            setTemplates([]); });
+        return () => { cancelled = true; };
+    }, [tmplOpen, templates]);
+    // Games already known to the runtime host (mtime-sorted server-side).
+    // Fetched once on mount; drives the "open an existing project" section so a
+    // host that already has games never forces a create (§14 amendment:
+    // opening an existing game IS a valid init — enterHomeWith reuses the same
+    // pin + enter path as create/link). Filter out the `default` session stub so
+    // an empty instance does not show a fake "已有项目" row.
+    const [existingGames, setExistingGames] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        getStudioProjectClient().listProjects()
+            .then((j) => {
+            if (cancelled)
+                return;
+            setExistingGames(j.games
+                .filter((project) => isUserExistingGame(project.slug))
+                .map((project) => ({ slug: project.slug, name: project.name ?? project.slug })));
+        })
+            .catch(() => { if (!cancelled)
+            setExistingGames([]); });
+        return () => { cancelled = true; };
+    }, []);
+    // Create/link materializes the game; selection uses the one active-game write.
+    const enterHomeWith = useCallback(async (slug) => {
+        if (slug)
+            await setActiveGame(slug);
+        const transition = resolveHomeOnboarding(loadOnboarding(), tourEnabled);
+        // Latch Scene + default layout intent before shell mounts (onReady race).
+        if (transition.shouldRunTour)
+            latchTourShellDefaults();
+        setTourActive(transition.shouldRunTour);
+        saveOnboarding(transition.state);
+        setPhaseState(transition.state.phase);
+        window.dispatchEvent(new CustomEvent(APP_EVENTS.onboardingChanged));
+    }, [setActiveGame, tourEnabled]);
+    // Open a game that already exists in the active root: no create, no link —
+    // just pin + enter home. Reuses the 'open' busy label ("opening…").
+    const openExisting = useCallback(async (slug) => {
+        setProjBusy(true);
+        setProjBusyKind('open');
+        setProjErr(null);
+        try {
+            await enterHomeWith(slug);
+        }
+        catch (e) {
+            setProjErr(e.message);
+            setProjBusy(false);
+            setProjBusyKind(null);
+        }
+    }, [enterHomeWith]);
+    // Do the actual game create/link. Open games remain at their canonical paths;
+    // newly-created games use the runtime host's default game store.
+    const execIntent = useCallback(async (intent) => {
+        if (intent.kind === 'open') {
+            const j = await getStudioProjectClient().linkProject(intent.path);
+            if (!j.ok)
+                throw new Error(j.error ?? 'Unable to link project');
+            await enterHomeWith(j.slug ?? '');
+            return;
+        }
+        const slug = toGameSlug(intent.name);
+        const j = await getStudioProjectClient().createProject({
+            slug,
+            name: intent.name.trim() || slug,
+            brief: '',
+            ...(intent.kind === 'template' ? { template: intent.template } : {}),
+        });
+        if (!j.ok)
+            throw new Error(j.error ?? 'Unable to create project');
+        await enterHomeWith(j.slug ?? slug);
+    }, [enterHomeWith]);
+    // Entry point for all three project actions. There is no root-switch or
+    // Project creation/opening is a game operation; no root-switch intent exists.
+    const startAction = useCallback(async (intent) => {
+        let next = intent;
+        if (intent.kind !== 'open') {
+            const existing = (existingGames ?? []).map((g) => g.slug);
+            const resolved = resolveProjectName(intent.name, existing);
+            next = { ...intent, name: resolved.name };
+        }
+        setProjBusy(true);
+        setProjBusyKind(next.kind);
+        setProjErr(null);
+        try {
+            await execIntent(next);
+        }
+        catch (e) {
+            setProjErr(formatProjectError(e.message, t));
+            setProjBusy(false);
+            setProjBusyKind(null);
+        }
+    }, [execIntent, existingGames, t]);
+    const onLang = (next) => { setLang(next); changeLanguage(next); };
+    // Steps trace the default Scene layout in do-a-game order: viewport → scene
+    // outline/properties → top bar → footer (content browser + info now collapse
+    // into the global footer, so the tour anchors the footer instead of a live CB
+    // panel) → chat. Each anchorId matches a `data-tour-id` (hierarchy via
+    // panelRegistry EP_TOUR_IDS, preview on the viewport panel, topbar on the
+    // TopBar root, footer on the StatusBar host, chat on the chat panel).
+    const TOUR_STEPS = [
+        { anchorId: 'preview', anchor: t('onboarding.tour.preview.anchor'), body: t('onboarding.tour.preview.body') },
+        { anchorId: ['hierarchy', 'inspector'], anchor: t('onboarding.tour.hierarchy.anchor'), body: t('onboarding.tour.hierarchy.body') },
+        { anchorId: 'topbar', anchor: t('onboarding.tour.topbar.anchor'), body: t('onboarding.tour.topbar.body') },
+        { anchorId: 'footer', anchor: t('onboarding.tour.footer.anchor'), body: t('onboarding.tour.footer.body') },
+        { anchorId: 'chat', anchor: t('onboarding.tour.chat.anchor'), body: t('onboarding.tour.chat.body') },
+    ];
+    // Tour is the last onboarding-owned step; the first-chat hint lives in the
+    // chat empty state. Mark the tour done and go inert (phase → 'done'), then
+    // notify the chat so its hint can appear this session (no reload needed).
+    const endTour = useCallback(() => {
+        setTourActive(false);
+        const prev = loadOnboarding();
+        saveOnboarding({ ...prev, phase: 'done', done: { ...prev.done, tour: true } });
+        setPhaseState('done');
+        window.dispatchEvent(new CustomEvent(APP_EVENTS.onboardingChanged));
+    }, []);
+    if (phase === 'done')
+        return null;
+    // ── HOME PHASE: no dark scrim — overlay the live shell with the tour, then nudge ──
+    if (phase === 'home') {
+        return (_jsx(_Fragment, { children: tourActive && (_jsx(TourOverlay, { steps: TOUR_STEPS, stepIndex: tourIdx, onStepChange: setTourIdx, onClose: () => endTour(), labels: {
+                    prev: t('onboarding.tour.prev'),
+                    skip: t('onboarding.tour.skip'),
+                    next: t('onboarding.tour.next'),
+                    done: t('onboarding.tour.done'),
+                } })) }));
+    }
+    // ── WELCOME / PROJECT PHASES: dark modal over the shell ──
+    const stepStrip = (_jsx("div", { className: "fx-ob-strip", children: PHASE_ORDER.map((s, i) => {
+            const cur = PHASE_ORDER.indexOf(phase);
+            const active = s === phase;
+            const passed = cur > i;
+            return (_jsxs("span", { style: { display: 'inline-flex', alignItems: 'center', gap: 6 }, children: [_jsx("span", { className: `fx-ob-dot${active ? ' active' : passed ? ' passed' : ''}` }), _jsx("span", { className: `fx-ob-lbl${active ? ' active' : ''}`, children: t(`onboarding.step.${s}`) }), i < PHASE_ORDER.length - 1 && _jsx("span", { className: "fx-ob-bar" })] }, s));
+        }) }));
+    return (_jsxs("div", { className: "fx-ob-overlay", role: "dialog", "aria-modal": "true", "aria-label": t('onboarding.welcome.title'), children: [_jsxs("div", { className: "fx-ob-card-shell", children: [stepStrip, _jsx("div", { className: "fx-ob-frame", children: _jsx("div", { className: "fx-ob-frame-body", children: phase === 'welcome' ? (_jsx(WelcomeView, { t: t, lang: lang, onLang: onLang, selected: selected, setSelected: (v) => { setSelected(v); resetCheck(); }, baseUrl: baseUrl, setBaseUrl: (v) => { setBaseUrl(v); if (checkResult)
+                                    resetCheck(); }, apiKey: apiKey, setApiKey: (v) => { setApiKey(v); if (checkResult)
+                                    resetCheck(); }, cli: cli, setCli: (v) => { setCli(v); resetCheck(); }, cliProviders: cliProviders, checking: checking, checkResult: checkResult, checkFailMsg: checkFailMsg, connectedList: connectedList() })) : (_jsx(ProjectView, { t: t, projName: projName, setProjName: (v) => { setProjName(v); if (projErr)
+                                    setProjErr(null); }, busy: projBusy, busyKind: projBusyKind, err: projErr, onNew: () => void startAction({ kind: 'new', name: projName }), onTemplate: () => { setTmplSlug(null); setTmplOpen(true); }, onOpen: () => setFsOpen(true), existingGames: existingGames, onOpenExisting: (slug) => void openExisting(slug) })) }) }), _jsxs("div", { className: "fx-ob-row", style: { marginTop: 10 }, children: [_jsx("div", { className: "fx-ob-grow" }), phase === 'welcome' && (_jsxs(_Fragment, { children: [_jsx("button", { className: "fx-ob-btn fx-ob-btn-ghost", onClick: skipConnect, children: t('onboarding.skip') }), _jsx("button", { className: "fx-ob-btn fx-ob-btn-primary", disabled: checking, onClick: () => {
+                                            if (checking)
+                                                return;
+                                            if (countdown !== null) {
+                                                resetCheck();
+                                                setPhase('project');
+                                                return;
+                                            }
+                                            void runCheck();
+                                        }, children: checking ? t('onboarding.check.checking') : countdown !== null ? t('onboarding.nextCountdown', { n: countdown }) : t('onboarding.next') })] }))] })] }), phase === 'project' && tmplOpen && (_jsx(TemplateModal, { t: t, templates: templates, selected: tmplSlug, onSelect: setTmplSlug, onCancel: () => setTmplOpen(false), onConfirm: () => { if (tmplSlug) {
+                    setTmplOpen(false);
+                    void startAction({ kind: 'template', name: projName, template: tmplSlug });
+                } }, busy: projBusy })), phase === 'project' && fsOpen && (_jsx("div", { className: "fx-ob-modal-scrim", onClick: (e) => { if (e.target === e.currentTarget)
+                    setFsOpen(false); }, children: _jsx("div", { className: "fx-ob-modal", children: _jsxs("div", { className: "fx-ob-modal-inner", children: [_jsx("h3", { className: "fx-ob-h3", children: t('onboarding.project.openTitle') }), _jsx(FsBrowser, { initialDir: "~", onPick: (absPath) => { setFsOpen(false); void startAction({ kind: 'open', path: absPath }); }, onCancel: () => setFsOpen(false) })] }) }) }))] }));
+}
+function ConnectCard({ selected, onSelect, title, sub, children, }) {
+    return (_jsx("div", { className: `fx-ob-card fx-ob-connect-card${selected ? ' sel' : ''}`, onClick: onSelect, role: "button", tabIndex: 0, 
+        // Prevent focusing the card on mouse click: focus inside the overflow:auto
+        // shell triggers scroll-into-view and looks like the text "shrinks"/jitters.
+        // Keyboard users still get focus via Tab + Enter/Space.
+        onMouseDown: (e) => {
+            const t = e.target;
+            if (t.closest('input, textarea, button, [role="combobox"]'))
+                return;
+            e.preventDefault();
+        }, onKeyDown: (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                onSelect();
+            }
+        }, children: _jsx("div", { className: "fx-ob-card-cb", children: _jsxs("div", { className: "fx-ob-stack fx-ob-gap6", children: [_jsx("span", { className: "fx-ob-connect-title", children: title }), _jsx("div", { className: "fx-ob-small fx-ob-sec", children: sub }), children] }) }) }));
+}
+function WelcomeView(props) {
+    const { t } = props;
+    return (_jsxs("div", { className: "fx-ob-stack fx-ob-gap14", children: [_jsxs("div", { className: "fx-ob-stack fx-ob-gap6", children: [_jsx("h2", { className: "fx-ob-h2", children: t('onboarding.welcome.title') }), _jsx("div", { className: "fx-ob-sec", children: t('onboarding.welcome.lead') })] }), _jsxs("div", { className: "fx-ob-row", children: [_jsx("span", { className: "fx-ob-small fx-ob-muted", children: t('onboarding.welcome.language') }), _jsx("span", { className: `fx-ob-pill${props.lang === 'zh' ? ' active' : ''}`, onClick: () => props.onLang('zh'), children: "\u4E2D\u6587" }), _jsx("span", { className: `fx-ob-pill${props.lang === 'en' ? ' active' : ''}`, onClick: () => props.onLang('en'), children: "English" })] }), _jsx("div", { className: "fx-ob-divider" }), _jsxs("div", { className: "fx-ob-stack fx-ob-gap8", children: [_jsxs("div", { className: "fx-ob-stack fx-ob-gap6", children: [_jsx("h3", { className: "fx-ob-h3", children: t('onboarding.connect.title') }), _jsx("div", { className: "fx-ob-tiny fx-ob-muted", children: t('onboarding.connect.hint') })] }), _jsxs("div", { className: "fx-ob-stack fx-ob-gap8", children: [_jsx(ConnectCard, { selected: props.selected === 'key', onSelect: () => props.setSelected('key'), title: t('onboarding.connect.keyTitle'), sub: t('onboarding.connect.keySub'), children: _jsxs("div", { className: "fx-ob-stack fx-ob-gap6", style: { marginTop: 10 }, onClick: (e) => e.stopPropagation(), children: [_jsx("input", { className: "fx-ob-input", placeholder: "Base URL, e.g. https://api.openai.com/v1", value: props.baseUrl, onChange: (e) => {
+                                                if (props.selected !== 'key')
+                                                    props.setSelected('key');
+                                                props.setBaseUrl(e.target.value);
+                                            }, onFocus: () => { if (props.selected !== 'key')
+                                                props.setSelected('key'); } }), _jsx("input", { className: "fx-ob-input", type: "password", placeholder: "API Key", value: props.apiKey, onChange: (e) => {
+                                                if (props.selected !== 'key')
+                                                    props.setSelected('key');
+                                                props.setApiKey(e.target.value);
+                                            }, onFocus: () => { if (props.selected !== 'key')
+                                                props.setSelected('key'); } })] }) }), _jsx(ConnectCard, { selected: props.selected === 'cli', onSelect: () => props.setSelected('cli'), title: t('onboarding.connect.cliTitle'), sub: t('onboarding.connect.cliSub'), children: _jsx("div", { style: { marginTop: 10 }, onClick: (e) => e.stopPropagation(), children: _jsxs(Select, { value: props.cli, onValueChange: (v) => {
+                                            if (props.selected !== 'cli')
+                                                props.setSelected('cli');
+                                            props.setCli(v);
+                                        }, onOpenChange: (open) => {
+                                            if (open && props.selected !== 'cli')
+                                                props.setSelected('cli');
+                                        }, children: [_jsx(SelectTrigger, { className: "rounded-[6px] border-[color:var(--ob-stroke-1)] text-[color:var(--ob-text)]", children: _jsx(SelectValue, {}) }), _jsx(SelectContent, { className: "z-[var(--z-toplevel)]", children: cliIdsFrom(props.cliProviders).map((id) => (_jsx(SelectItem, { value: id, children: _jsx(CliOptionLabel, { t: t, id: id, providers: props.cliProviders }) }, id))) })] }) }) })] })] }), props.checking && _jsx("div", { className: "fx-ob-callout info", children: t('onboarding.check.checking') }), !props.checking && props.checkResult === 'ok' && (_jsx("div", { className: "fx-ob-callout ok", children: t('onboarding.check.ok', { list: props.connectedList.join(' / ') }) })), !props.checking && props.checkResult === 'fail' && (_jsx("div", { className: "fx-ob-callout err", children: props.checkFailMsg }))] }));
+}
+function ProjectView(props) {
+    const { t } = props;
+    const resolved = resolveProjectName(props.projName, (props.existingGames ?? []).map((g) => g.slug));
+    const busyMsg = props.busyKind ? t(`onboarding.project.busy.${props.busyKind}`) : t('onboarding.project.busy.new');
+    // "New"/"template" create a game in the runtime host; "open" adopts
+    // an existing game dir at any path (name not needed — derived server-side).
+    // Empty name auto-resolves to untitled-N — never block create on the name field.
+    const cards = [
+        { id: 'new', title: t('onboarding.project.newTitle'), desc: t('onboarding.project.newDesc'), cta: t('onboarding.project.newCta'), onGo: props.onNew },
+        { id: 'sample', title: t('onboarding.project.sampleTitle'), desc: t('onboarding.project.sampleDesc'), cta: t('onboarding.project.sampleCta'), onGo: props.onTemplate },
+        { id: 'open', title: t('onboarding.project.openTitle'), desc: t('onboarding.project.openDesc'), cta: t('onboarding.project.openCta'), onGo: props.onOpen },
+    ];
+    return (_jsxs("div", { className: "fx-ob-stack fx-ob-gap12", children: [_jsx("h2", { className: "fx-ob-h2", children: t('onboarding.project.title') }), props.busy && (_jsxs("div", { className: "fx-ob-callout info fx-ob-busy", role: "status", "aria-live": "polite", children: [_jsx("span", { className: "fx-ob-spinner", "aria-hidden": "true" }), _jsx("span", { children: busyMsg })] })), props.existingGames && props.existingGames.length > 0 && (_jsxs("div", { className: "fx-ob-panel", children: [_jsx("div", { className: "fx-ob-row", children: _jsx("span", { className: "fx-ob-small fx-ob-sec", style: { fontWeight: 500 }, children: t('onboarding.project.existingTitle') }) }), _jsx("div", { className: "fx-ob-tiny", style: { color: 'var(--ob-text-4)', marginTop: 4 }, children: t('onboarding.project.existingDesc', { count: String(props.existingGames.length) }) }), _jsx("div", { className: "fx-ob-stack fx-ob-gap8", style: { marginTop: 8, maxHeight: 180, overflowY: 'auto' }, children: props.existingGames.map((g) => (_jsx("div", { className: "fx-ob-card", style: { cursor: props.busy ? 'default' : 'pointer' }, onClick: () => { if (!props.busy)
+                                props.onOpenExisting(g.slug); }, children: _jsx("div", { className: "fx-ob-card-cb", children: _jsxs("div", { className: "fx-ob-row", children: [_jsx("span", { className: "fx-ob-small", children: g.name }), _jsx("span", { className: "fx-ob-tiny fx-ob-muted", style: { marginLeft: 8 }, children: g.slug }), _jsx("div", { className: "fx-ob-grow" }), _jsx("span", { className: "fx-ob-pill sm static", children: t('onboarding.project.existingOpen') })] }) }) }, g.slug))) })] })), _jsxs("div", { className: "fx-ob-panel", children: [_jsx("div", { className: "fx-ob-row", style: { marginTop: 8 }, children: _jsx("span", { className: "fx-ob-small fx-ob-sec", style: { fontWeight: 500 }, children: t('onboarding.project.name') }) }), _jsx("div", { className: "fx-ob-row", style: { marginTop: 6 }, children: _jsx("input", { className: "fx-ob-input", style: { flex: 1, minWidth: 0 }, placeholder: t('onboarding.project.namePlaceholder'), value: props.projName, onChange: (e) => props.setProjName(e.target.value) }) }), _jsx("div", { className: "fx-ob-tiny", style: { color: 'var(--ob-text-4)', marginTop: 6 }, children: t('onboarding.project.willCreate', { name: resolved.slug }) })] }), _jsx("div", { className: "fx-ob-grid3", children: cards.map((o) => (_jsxs("div", { className: "fx-ob-card", children: [_jsx("div", { className: "fx-ob-card-ch", children: _jsx("span", { children: o.title }) }), _jsx("div", { className: "fx-ob-card-cb", children: _jsxs("div", { className: "fx-ob-stack fx-ob-gap8", children: [_jsx("div", { className: "fx-ob-small fx-ob-sec", children: o.desc }), _jsx("button", { className: "fx-ob-btn fx-ob-btn-secondary fx-ob-btn-block", disabled: props.busy, onClick: o.onGo, children: o.cta })] }) })] }, o.id))) }), props.err && _jsx("div", { className: "fx-ob-callout err", children: props.err }), _jsx("div", { className: "fx-ob-tiny fx-ob-muted", children: t('onboarding.project.footer') })] }));
+}
+function TemplateModal(props) {
+    const { t } = props;
+    const loading = props.templates === null;
+    const empty = !loading && props.templates.length === 0;
+    return (_jsx("div", { className: "fx-ob-modal-scrim", onClick: (e) => { if (e.target === e.currentTarget)
+            props.onCancel(); }, children: _jsx("div", { className: "fx-ob-modal", children: _jsxs("div", { className: "fx-ob-modal-inner", children: [_jsx("h3", { className: "fx-ob-h3", children: t('onboarding.template.title') }), loading && _jsx("div", { className: "fx-ob-small fx-ob-muted", children: t('onboarding.template.loading') }), empty && _jsx("div", { className: "fx-ob-small fx-ob-muted", children: t('onboarding.template.empty') }), !loading && !empty && (_jsx("div", { className: "fx-ob-stack fx-ob-gap8", style: { maxHeight: 320, overflowY: 'auto' }, children: props.templates.map((tpl) => (_jsx("div", { className: `fx-ob-card${props.selected === tpl.slug ? ' sel' : ''}`, style: { cursor: 'pointer' }, onClick: () => props.onSelect(tpl.slug), children: _jsx("div", { className: "fx-ob-card-cb", children: _jsxs("div", { className: "fx-ob-row", children: [_jsx("span", { className: "fx-ob-small", children: tpl.name }), _jsx("span", { className: "fx-ob-tiny fx-ob-muted", style: { marginLeft: 8 }, children: tpl.slug }), _jsx("div", { className: "fx-ob-grow" }), props.selected === tpl.slug && _jsx("span", { className: "fx-ob-pill sm active static", children: t('onboarding.template.picked') })] }) }) }, tpl.slug))) })), _jsxs("div", { className: "fx-ob-row", style: { justifyContent: 'flex-end' }, children: [_jsx("button", { className: "fx-ob-btn fx-ob-btn-ghost", onClick: props.onCancel, children: t('onboarding.template.cancel') }), _jsx("button", { className: "fx-ob-btn fx-ob-btn-primary", disabled: props.selected === null || props.busy, onClick: props.onConfirm, children: t('onboarding.template.confirm') })] })] }) }) }));
+}

package/dist/package/node/components/Onboarding/connect-selection.js

@@ -0,0 +1,18 @@
+/** True when Next must block — user has not picked API Key or local CLI yet.
+ *  (Skip still advances without a selection.) */
+export function needsConnectSelection(selected) {
+    return selected === null;
+}
+export function validateApiKeyFields(baseUrl, apiKey) {
+    if (!baseUrl.trim() || !apiKey.trim())
+        return 'empty';
+    return 'ok';
+}
+/** Live `/v1/models` probe result from `list_models` (server merges disk+live).
+ *  Disk fallback must NOT count as connected — only a real live/cache hit. */
+export function interpretLiveCatalogProbe(live) {
+    const source = live?.source;
+    if (source === 'live' || source === 'cache')
+        return { ok: true };
+    return { ok: false, error: live?.error };
+}

package/dist/package/node/components/Onboarding/home-transition.js

@@ -0,0 +1,20 @@
+/** Product policy and persisted progress jointly decide whether the shell tour mounts. */
+export function shouldActivateTour(tourEnabled, state) {
+    return tourEnabled && !state.done.tour;
+}
+/** Resolve setup → shell without parking a disabled/completed tour in `home`. */
+export function resolveHomeOnboarding(state, tourEnabled) {
+    const shouldRunTour = shouldActivateTour(tourEnabled, state);
+    if (shouldRunTour)
+        return { shouldRunTour, state: { ...state, phase: 'home' } };
+    if (state.phase === 'done' && state.done.tour)
+        return { shouldRunTour, state };
+    return {
+        shouldRunTour,
+        state: {
+            ...state,
+            phase: 'done',
+            done: { ...state.done, tour: true },
+        },
+    };
+}

package/dist/package/node/components/Onboarding/index.js

@@ -0,0 +1,3 @@
+export { OnboardingController } from './OnboardingController.js';
+export { ConnectModelPrompt } from './ConnectModelPrompt.js';
+export { loadOnboarding, saveOnboarding, PHASE_ORDER } from './types.js';

package/dist/package/node/components/Onboarding/prepareTourShell.js

@@ -0,0 +1,11 @@
+import { bumpDockResetEpoch } from '../DockShell/dockResetEpoch.js';
+/** Latch a reset before the Page dock mounts. */
+export function latchTourShellDefaults() {
+    bumpDockResetEpoch();
+}
+/** Open the real project editor Page used by the tour and reset its layout. */
+export function prepareTourShell(host) {
+    void host.pages.open({ typeId: '@forgeax/editor#page/level' })
+        .then(() => host.commands.execute('app.dock.reset'))
+        .catch(() => undefined);
+}