@forgeax/interface 0.4.1

package/dist/package/browser/components/TopBar/IosPackageDialog.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useRef } from 'react';
+import { Apple, Image as ImageIcon, Trash2, RectangleHorizontal, RectangleVertical } from 'lucide-react';
+import './TopBar.css';
+// Mirror the backend validation (IosPackager.ts) so bad input is caught before
+// the round-trip; the backend still re-validates as a safety net.
+const BUNDLE_ID_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+const PROJECT_NAME_RE = /^[A-Za-z0-9_-]+$/;
+const MAX_ICON_BYTES = 2 * 1024 * 1024;
+/** Derive a sane default bundle identifier from a slug (matches the backend). */
+export function defaultIosBundleId(slug) {
+    let seg = slug.toLowerCase().replace(/[^a-z0-9]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+    if (!seg)
+        seg = 'app';
+    if (/^[0-9]/.test(seg))
+        seg = `g${seg}`;
+    return `com.forgeax.game.${seg}`;
+}
+export function IosPackageDialog({ slug, defaultAppName, onCancel, onConfirm, t }) {
+    const [bundleId, setBundleId] = useState(defaultIosBundleId(slug));
+    const [appName, setAppName] = useState(defaultAppName || slug);
+    const [projectName, setProjectName] = useState(slug);
+    const [orientation, setOrientation] = useState('landscape');
+    const [icon, setIcon] = useState();
+    const [iconError, setIconError] = useState('');
+    const fileInputRef = useRef(null);
+    const bundleIdValid = BUNDLE_ID_RE.test(bundleId.trim());
+    const appNameValid = appName.trim().length >= 1 && appName.trim().length <= 30;
+    const projectNameValid = PROJECT_NAME_RE.test(projectName.trim());
+    const canSubmit = bundleIdValid && appNameValid && projectNameValid && !iconError;
+    const onPickIcon = (e) => {
+        setIconError('');
+        const file = e.target.files?.[0];
+        if (!file)
+            return;
+        if (file.type !== 'image/png') {
+            setIconError(t('topbar.ios.iconErrType'));
+            return;
+        }
+        if (file.size > MAX_ICON_BYTES) {
+            setIconError(t('topbar.ios.iconErrSize'));
+            return;
+        }
+        const reader = new FileReader();
+        reader.onload = () => {
+            const dataUrl = String(reader.result ?? '');
+            const comma = dataUrl.indexOf(',');
+            const b64 = comma >= 0 ? dataUrl.slice(comma + 1) : '';
+            setIcon({ dataBase64: b64, filename: file.name, previewUrl: dataUrl });
+        };
+        reader.onerror = () => setIconError(t('topbar.ios.iconErrType'));
+        reader.readAsDataURL(file);
+    };
+    const submit = () => {
+        if (!canSubmit)
+            return;
+        onConfirm({
+            iosBundleId: bundleId.trim(),
+            iosAppName: appName.trim(),
+            iosProjectName: projectName.trim(),
+            iosIcon: icon ? { dataBase64: icon.dataBase64, filename: icon.filename } : undefined,
+            iosOrientation: orientation,
+        });
+    };
+    const labelStyle = { fontSize: 12, fontWeight: 600, marginBottom: 4, display: 'block' };
+    const inputStyle = {
+        width: '100%', boxSizing: 'border-box', fontSize: 13, padding: '6px 8px', borderRadius: 4,
+        border: '1px solid rgba(255,255,255,0.15)', background: 'rgba(0,0,0,0.25)', color: 'inherit',
+    };
+    const hintStyle = { fontSize: 11, opacity: 0.6, marginTop: 3 };
+    const errStyle = { fontSize: 11, color: '#f87171', marginTop: 3 };
+    return (_jsx("div", { className: "tb-progress-overlay", onClick: (e) => { if (e.target === e.currentTarget)
+            onCancel(); }, children: _jsxs("div", { className: "tb-progress-dialog", style: { minWidth: 440, maxWidth: 520 }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 4 }, children: [_jsx(Apple, { size: 16 }), _jsx("span", { style: { fontWeight: 600, fontSize: 14 }, children: t('topbar.ios.title') })] }), _jsx("div", { style: { fontSize: 12, opacity: 0.7, marginBottom: 14 }, children: t('topbar.ios.subtitle') }), _jsxs("div", { style: { marginBottom: 12 }, children: [_jsx("label", { style: labelStyle, children: t('topbar.ios.bundleIdLabel') }), _jsx("input", { style: { ...inputStyle, borderColor: bundleIdValid ? inputStyle.border : '#f87171' }, value: bundleId, spellCheck: false, autoCapitalize: "off", onChange: (e) => setBundleId(e.target.value), placeholder: "com.acme.mygame" }), bundleIdValid
+                            ? _jsx("div", { style: hintStyle, children: t('topbar.ios.bundleIdHint') })
+                            : _jsx("div", { style: errStyle, children: t('topbar.ios.bundleIdError') })] }), _jsxs("div", { style: { marginBottom: 12 }, children: [_jsx("label", { style: labelStyle, children: t('topbar.ios.appNameLabel') }), _jsx("input", { style: { ...inputStyle, borderColor: appNameValid ? inputStyle.border : '#f87171' }, value: appName, onChange: (e) => setAppName(e.target.value), maxLength: 30 }), !appNameValid && _jsx("div", { style: errStyle, children: t('topbar.ios.appNameError') })] }), _jsxs("div", { style: { marginBottom: 12 }, children: [_jsx("label", { style: labelStyle, children: t('topbar.ios.projectNameLabel') }), _jsx("input", { style: { ...inputStyle, borderColor: projectNameValid ? inputStyle.border : '#f87171' }, value: projectName, spellCheck: false, autoCapitalize: "off", onChange: (e) => setProjectName(e.target.value) }), projectNameValid
+                            ? _jsx("div", { style: hintStyle, children: t('topbar.ios.projectNameHint') })
+                            : _jsx("div", { style: errStyle, children: t('topbar.ios.projectNameError') })] }), _jsxs("div", { style: { marginBottom: 12 }, children: [_jsx("label", { style: labelStyle, children: t('topbar.ios.orientationLabel') }), _jsx("div", { style: { display: 'flex', gap: 8 }, children: ([
+                                { value: 'landscape', icon: _jsx(RectangleHorizontal, { size: 14 }), label: t('topbar.ios.orientationLandscape') },
+                                { value: 'portrait', icon: _jsx(RectangleVertical, { size: 14 }), label: t('topbar.ios.orientationPortrait') },
+                            ]).map((opt) => {
+                                const active = orientation === opt.value;
+                                return (_jsxs("button", { type: "button", onClick: () => setOrientation(opt.value), style: {
+                                        flex: 1, display: 'inline-flex', alignItems: 'center', justifyContent: 'center', gap: 6,
+                                        fontSize: 12, cursor: 'pointer', padding: '7px 10px', borderRadius: 4,
+                                        border: `1px solid ${active ? 'var(--accent, #3b82f6)' : 'rgba(255,255,255,0.15)'}`,
+                                        background: active ? 'rgba(59,130,246,0.18)' : 'rgba(0,0,0,0.25)',
+                                        color: 'inherit', fontWeight: active ? 600 : 400,
+                                    }, children: [opt.icon, opt.label] }, opt.value));
+                            }) }), _jsx("div", { style: hintStyle, children: t('topbar.ios.orientationHint') })] }), _jsxs("div", { style: { marginBottom: 16 }, children: [_jsx("label", { style: labelStyle, children: t('topbar.ios.iconLabel') }), _jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 12 }, children: [_jsx("div", { style: {
+                                        width: 56, height: 56, borderRadius: 10, flexShrink: 0,
+                                        border: '1px solid rgba(255,255,255,0.15)', overflow: 'hidden',
+                                        display: 'flex', alignItems: 'center', justifyContent: 'center',
+                                        background: 'rgba(0,0,0,0.25)',
+                                    }, children: icon
+                                        ? _jsx("img", { src: icon.previewUrl, alt: "", style: { width: '100%', height: '100%', objectFit: 'cover' } })
+                                        : _jsx(ImageIcon, { size: 22, style: { opacity: 0.4 } }) }), _jsxs("div", { style: { flex: 1, minWidth: 0 }, children: [_jsxs("button", { type: "button", onClick: () => { const el = fileInputRef.current; if (el) {
+                                                el.value = '';
+                                                el.click();
+                                            } }, style: {
+                                                display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: 12, cursor: 'pointer',
+                                                padding: '5px 10px', borderRadius: 4, border: '1px solid rgba(255,255,255,0.18)',
+                                                background: 'transparent', color: 'inherit',
+                                            }, children: [_jsx(ImageIcon, { size: 13 }), t('topbar.ios.iconPick')] }), _jsx("input", { ref: fileInputRef, type: "file", accept: "image/png", style: { display: 'none' }, onChange: onPickIcon }), icon && (_jsxs("button", { type: "button", onClick: () => { setIcon(undefined); setIconError(''); }, title: t('topbar.ios.iconRemove'), style: {
+                                                marginLeft: 8, fontSize: 12, cursor: 'pointer', background: 'none',
+                                                border: 'none', color: 'inherit', opacity: 0.6, display: 'inline-flex',
+                                                alignItems: 'center', gap: 3, verticalAlign: 'middle',
+                                            }, children: [_jsx(Trash2, { size: 12 }), " ", t('topbar.ios.iconRemove')] })), _jsx("div", { style: hintStyle, children: icon ? icon.filename : t('topbar.ios.iconHint') }), iconError && _jsx("div", { style: errStyle, children: iconError })] })] })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'flex-end', gap: 8, marginTop: 18 }, children: [_jsx("button", { type: "button", onClick: onCancel, style: {
+                                fontSize: 13, cursor: 'pointer', padding: '6px 14px', borderRadius: 4,
+                                border: '1px solid rgba(255,255,255,0.18)', background: 'transparent', color: 'inherit',
+                            }, children: t('topbar.ios.cancel') }), _jsx("button", { type: "button", onClick: submit, disabled: !canSubmit, style: {
+                                fontSize: 13, cursor: canSubmit ? 'pointer' : 'not-allowed', padding: '6px 14px',
+                                borderRadius: 4, border: 'none', color: '#fff',
+                                background: canSubmit ? 'var(--accent, #3b82f6)' : 'rgba(120,120,120,0.4)',
+                            }, children: t('topbar.ios.confirm') })] })] }) }));
+}

package/dist/package/browser/components/TopBar/ProjectSwitcher.d.ts

@@ -0,0 +1,3 @@
+import './FsBrowser.css';
+import './TopBar.css';
+export declare function GameDirectoryModalHost(): import("react/jsx-runtime").JSX.Element | null;

package/dist/package/browser/components/TopBar/ProjectSwitcher.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Game-directory open modal and project-id synchronisation.
+//
+// A Studio project is exactly one game directory. The runtime host may mount
+// that directory internally for the engine, but it is never exposed as a
+// project/game directory to the user.
+import { useState } from 'react';
+import { useTranslation } from '../../i18n';
+import { getStudioProjectClient, useShellStore } from '../../store';
+import { FsBrowser } from './FsBrowser';
+import './FsBrowser.css';
+import './TopBar.css';
+export function GameDirectoryModalHost() {
+    const open = useShellStore((s) => s.gameDirectoryModalOpen);
+    const close = useShellStore((s) => s.closeGameDirectoryModal);
+    if (!open)
+        return null;
+    return _jsx(OpenGameDirectoryModal, { onClose: close });
+}
+function OpenGameDirectoryModal({ onClose }) {
+    const { t } = useTranslation();
+    const [err, setErr] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const setActiveGame = useShellStore((s) => s.setActiveGame);
+    const submitOpen = async (absPath) => {
+        setBusy(true);
+        setErr(null);
+        try {
+            const j = await getStudioProjectClient().linkProject(absPath);
+            if (!j.ok || !j.slug)
+                throw new Error(j.error ?? 'Unable to link project');
+            onClose();
+            await setActiveGame(j.slug);
+        }
+        catch (e) {
+            setErr(e.message);
+            setBusy(false);
+        }
+    };
+    return (_jsx("div", { className: "tb-modal-overlay", onClick: onClose, children: _jsxs("div", { className: "tb-modal tb-modal-wide", onClick: (e) => e.stopPropagation(), children: [_jsx("div", { className: "tb-modal-title", children: t('gameDirectory.openTitle') }), _jsx(FsBrowser, { initialDir: "~", onPick: submitOpen, onCancel: onClose, busy: busy, externalError: err })] }) }));
+}

package/dist/package/browser/components/TopBar/PublishOnboarding.css

@@ -0,0 +1,133 @@
+/* First-run coach-mark for the Publish dropdown. Ported from
+   previews/publish-onboarding-preview.html, scoped with .fx-ob-* so it can't
+   collide with app styles. Rendered via portal to document.body. */
+
+/* Sit just above the dropdown content (--z-menu 10100) so the spotlight dims
+   the menu and the callout/finger render on top of it, but stay below toasts
+   (--z-toast) and tooltips (--z-tooltip). */
+.fx-ob-blocker {
+  position: fixed;
+  inset: 0;
+  z-index: calc(var(--z-menu, 10100) + 20);
+  background: transparent;
+  cursor: default;
+}
+
+/* The "hole": a transparent box whose huge box-shadow dims everything around
+   it. pointer-events:none so the element underneath stays visible/clickable. */
+.fx-ob-spot {
+  position: fixed;
+  z-index: calc(var(--z-menu, 10100) + 21);
+  border-radius: 10px;
+  pointer-events: none;
+  box-shadow: 0 0 0 9999px rgba(6, 6, 9, 0.72), 0 0 22px 4px rgba(212, 255, 72, 0.35);
+  border: 2px solid rgba(212, 255, 72, 0.85);
+  transition: top .3s cubic-bezier(.2, .8, .25, 1), left .3s cubic-bezier(.2, .8, .25, 1),
+    width .3s cubic-bezier(.2, .8, .25, 1), height .3s cubic-bezier(.2, .8, .25, 1);
+}
+
+.fx-ob-tip {
+  position: fixed;
+  z-index: calc(var(--z-menu, 10100) + 23);
+  width: 300px;
+  background: var(--surface, #17171c);
+  border: 1px solid var(--border-strong, rgba(255, 255, 255, 0.2));
+  border-radius: 14px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.55);
+  padding: 15px 16px 12px;
+  color: var(--text, #ececee);
+  transition: top .3s cubic-bezier(.2, .8, .25, 1), left .3s cubic-bezier(.2, .8, .25, 1);
+}
+
+.fx-ob-em {
+  color: var(--accent, #d4ff48);
+  display: inline-flex;
+}
+.fx-ob-title {
+  font-size: 15px;
+  font-weight: 700;
+  margin: 8px 0 6px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.fx-ob-tag {
+  font-size: 10px;
+  font-weight: 800;
+  color: #10120a;
+  background: var(--accent, #d4ff48);
+  padding: 2px 7px;
+  border-radius: 999px;
+}
+.fx-ob-desc {
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--text, #ececee);
+  margin: 0 0 6px;
+}
+.fx-ob-hint {
+  font-size: 12px;
+  color: var(--muted, rgba(255, 255, 255, 0.56));
+  margin: 8px 0 0;
+  display: flex;
+  align-items: flex-start;
+  gap: 6px;
+}
+.fx-ob-hint svg { flex: none; margin-top: 1px; color: var(--accent, #d4ff48); }
+
+.fx-ob-foot {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 12px;
+}
+.fx-ob-count { font-size: 11.5px; color: var(--faint, rgba(255, 255, 255, 0.4)); }
+.fx-ob-grow { flex: 1; }
+.fx-ob-btn {
+  height: 30px;
+  padding: 0 12px;
+  border-radius: 8px;
+  font-size: 12.5px;
+  cursor: pointer;
+  border: 1px solid var(--border, rgba(255, 255, 255, 0.1));
+  background: transparent;
+  color: var(--text, #ececee);
+  transition: background .12s ease, transform .1s ease;
+}
+.fx-ob-btn:hover { background: rgba(255, 255, 255, 0.06); }
+.fx-ob-btn:active { transform: scale(.97); }
+.fx-ob-btn.ghost { border-color: transparent; color: var(--faint, rgba(255, 255, 255, 0.4)); }
+.fx-ob-btn.primary {
+  background: var(--accent, #d4ff48);
+  color: #10120a;
+  border-color: var(--accent, #d4ff48);
+  font-weight: 700;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+.fx-ob-btn.primary:hover { background: #e2ff6b; }
+
+.fx-ob-arrow {
+  position: absolute;
+  width: 12px;
+  height: 12px;
+  background: var(--surface, #17171c);
+  border: 1px solid var(--border-strong, rgba(255, 255, 255, 0.2));
+  transform: rotate(45deg);
+}
+.fx-ob-tip[data-arrow="up"] .fx-ob-arrow { top: -7px; border-right: none; border-bottom: none; }
+.fx-ob-tip[data-arrow="right"] .fx-ob-arrow { right: -7px; border-left: none; border-bottom: none; }
+
+.fx-ob-finger {
+  position: fixed;
+  z-index: calc(var(--z-menu, 10100) + 22);
+  pointer-events: none;
+  color: var(--accent, #d4ff48);
+  animation: fxObPoint 1s ease-in-out infinite;
+}
+.fx-ob-finger svg { filter: drop-shadow(0 2px 4px rgba(0, 0, 0, .5)); }
+@keyframes fxObPoint {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-7px); }
+}

package/dist/package/browser/components/TopBar/PublishOnboarding.d.ts

@@ -0,0 +1,10 @@
+import './PublishOnboarding.css';
+type T = (key: string, opts?: Record<string, string | number>) => string;
+export interface PublishOnboardingProps {
+    active: boolean;
+    onClose: () => void;
+    setMenuOpen: (open: boolean) => void;
+    t: T;
+}
+export declare function PublishOnboarding({ active, onClose, setMenuOpen, t }: PublishOnboardingProps): import("react").ReactPortal | null;
+export {};

package/dist/package/browser/components/TopBar/PublishOnboarding.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { createRestartableTimeoutTaskLifecycle, installViewportResizeObservation, } from '@forgeax/app-shell/react';
+import { Rocket, Globe, Monitor, Laptop, Smartphone, Wrench, History, Eraser, Lightbulb, MousePointerClick, } from 'lucide-react';
+import { PUBLISH_OPTIONS, publishDoc } from './publish-options';
+import './PublishOnboarding.css';
+// tip title reuses the menu label; icon mirrors the menu item's icon.
+const LABEL_KEY = {
+    web: 'platformWeb', windows: 'platformWindows', macos: 'platformMac', android: 'platformAndroid',
+    engine: 'rebuildEngine', history: 'history', clean: 'clean',
+};
+function optionIcon(id) {
+    const sz = 24;
+    switch (id) {
+        case 'web': return _jsx(Globe, { size: sz });
+        case 'windows': return _jsx(Monitor, { size: sz });
+        case 'macos': return _jsx(Laptop, { size: sz });
+        case 'android': return _jsx(Smartphone, { size: sz });
+        case 'engine': return _jsx(Wrench, { size: sz });
+        case 'history': return _jsx(History, { size: sz });
+        case 'clean': return _jsx(Eraser, { size: sz });
+        default: return _jsx(Rocket, { size: sz });
+    }
+}
+function buildSteps(t) {
+    const intro = {
+        id: 'intro', sel: '.tb-publish-btn', place: 'below', menu: false, finger: true,
+        icon: _jsx(MousePointerClick, { size: 24 }),
+        title: t('topbar.onboard.introTitle'),
+        desc: t('topbar.onboard.introDesc'),
+        hint: t('topbar.onboard.introHint'),
+    };
+    const opts = PUBLISH_OPTIONS.filter((o) => !o.gray).map((o) => {
+        const d = publishDoc(t, o.id);
+        return {
+            id: o.id, sel: `[data-onboard="${o.id}"]`, place: 'left', menu: true,
+            icon: optionIcon(o.id),
+            title: t(`topbar.package.${LABEL_KEY[o.id] ?? o.id}`),
+            desc: d.what, hint: d.when,
+        };
+    });
+    return [intro, ...opts];
+}
+const TIP_W = 300;
+const TIP_H_EST = 175;
+const PAD = 6;
+function compute(el, step) {
+    const r = el.getBoundingClientRect();
+    const spot = { top: r.top - PAD, left: r.left - PAD, width: r.width + PAD * 2, height: r.height + PAD * 2 };
+    if (step.place === 'below') {
+        const left = Math.max(12, r.right - TIP_W);
+        const arrowPos = Math.min(TIP_W - 24, Math.max(16, r.left + r.width / 2 - left));
+        return {
+            spot, arrow: 'up', arrowPos,
+            tip: { left, top: r.bottom + 16 },
+            finger: step.finger ? { left: r.left + r.width / 2 - 12, top: r.bottom + 2 } : undefined,
+        };
+    }
+    const top = Math.max(12, Math.min(window.innerHeight - TIP_H_EST - 12, r.top + r.height / 2 - TIP_H_EST / 2));
+    const arrowPos = Math.min(TIP_H_EST - 24, Math.max(16, r.top + r.height / 2 - top));
+    return { spot, arrow: 'right', arrowPos, tip: { left: r.left - TIP_W - 20, top } };
+}
+export function PublishOnboarding({ active, onClose, setMenuOpen, t }) {
+    const steps = useMemo(() => buildSteps(t), [t]);
+    const optionTotal = steps.filter((s) => s.id !== 'intro').length;
+    const [idx, setIdx] = useState(0);
+    const [geo, setGeo] = useState(null);
+    useEffect(() => { if (active) {
+        setIdx(0);
+        setGeo(null);
+    } }, [active]);
+    const step = steps[idx];
+    // Drive the real dropdown: open it for option steps, close for the intro.
+    useEffect(() => {
+        if (!active || !step)
+            return;
+        setMenuOpen(step.menu);
+    }, [active, idx, step, setMenuOpen]);
+    const measure = useCallback(() => {
+        if (!step)
+            return false;
+        const el = document.querySelector(step.sel);
+        if (!el)
+            return false;
+        setGeo(compute(el, step));
+        return true;
+    }, [step]);
+    // The Radix menu items mount in a portal a tick after we request open, so
+    // retry measuring a few times before giving up.
+    useLayoutEffect(() => {
+        if (!active || !step)
+            return;
+        let tries = 0;
+        const run = () => { if (measure())
+            return; if (tries++ < 12)
+            retryTask.schedule(); };
+        const initialTask = createRestartableTimeoutTaskLifecycle({ task: run, delayMs: step.menu ? 150 : 20 });
+        const retryTask = createRestartableTimeoutTaskLifecycle({ task: run, delayMs: 45 });
+        initialTask.schedule();
+        return () => { initialTask.dispose(); retryTask.dispose(); };
+    }, [active, idx, step, measure]);
+    const finish = useCallback(() => { setMenuOpen(false); onClose(); }, [onClose, setMenuOpen]);
+    // Decide advance-vs-finish in the event handler, NOT inside the setIdx
+    // updater — React runs updaters during render, so calling finish() (which
+    // setState()s the parent TopBar) from there triggers a "setState while
+    // rendering a different component" warning.
+    const next = useCallback(() => {
+        if (idx >= steps.length - 1)
+            finish();
+        else
+            setIdx((i) => i + 1);
+    }, [idx, steps.length, finish]);
+    const prev = useCallback(() => setIdx((i) => Math.max(0, i - 1)), []);
+    useEffect(() => {
+        if (!active)
+            return;
+        const onResize = () => measure();
+        const disposeViewportResizeObservation = installViewportResizeObservation({
+            target: window,
+            onResize,
+        });
+        return () => { disposeViewportResizeObservation(); };
+    }, [active, measure, next, prev, finish]);
+    if (!active || !geo || !step)
+        return null;
+    const isLast = idx >= steps.length - 1;
+    const isOption = step.id !== 'intro';
+    const optNum = isOption ? steps.slice(0, idx + 1).filter((s) => s.id !== 'intro').length : 0;
+    return createPortal(_jsxs(_Fragment, { children: [_jsx("div", { className: "fx-ob-blocker", onClick: (e) => e.stopPropagation() }), _jsx("div", { className: "fx-ob-spot", style: { top: geo.spot.top, left: geo.spot.left, width: geo.spot.width, height: geo.spot.height } }), geo.finger && (_jsx("div", { className: "fx-ob-finger", style: { left: geo.finger.left, top: geo.finger.top }, children: _jsxs("svg", { viewBox: "0 0 24 24", width: 24, height: 24, fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("path", { d: "m9 9 5 12 1.8-5.2L21 14Z" }), _jsx("path", { d: "M7.2 2.2 8 5.1" }), _jsx("path", { d: "m5.1 8-2.9-.8" }), _jsx("path", { d: "M14 4.1 12 6" }), _jsx("path", { d: "m6 12-1.9 2" })] }) })), _jsxs("div", { className: "fx-ob-tip", "data-arrow": geo.arrow, tabIndex: -1, onKeyDown: (e) => {
+                    if (e.key === 'ArrowRight' || e.key === 'Enter') {
+                        e.preventDefault();
+                        next();
+                    }
+                    else if (e.key === 'ArrowLeft') {
+                        e.preventDefault();
+                        prev();
+                    }
+                    else if (e.key === 'Escape') {
+                        e.preventDefault();
+                        finish();
+                    }
+                }, style: { top: geo.tip.top, left: geo.tip.left }, children: [_jsx("span", { className: "fx-ob-arrow", style: geo.arrow === 'up' ? { left: geo.arrowPos } : { top: geo.arrowPos } }), _jsx("div", { className: "fx-ob-em", children: step.icon }), _jsx("div", { className: "fx-ob-title", children: step.title }), _jsx("p", { className: "fx-ob-desc", children: step.desc }), step.hint && (_jsxs("p", { className: "fx-ob-hint", children: [_jsx(Lightbulb, { size: 13 }), _jsx("span", { children: step.hint })] })), _jsxs("div", { className: "fx-ob-foot", children: [isOption && _jsx("span", { className: "fx-ob-count", children: t('topbar.onboard.counter', { n: optNum, total: optionTotal }) }), _jsx("span", { className: "fx-ob-grow" }), _jsx("button", { type: "button", className: "fx-ob-btn ghost", onClick: finish, children: t('topbar.onboard.skip') }), idx > 0 && _jsx("button", { type: "button", className: "fx-ob-btn", onClick: prev, children: t('topbar.onboard.prev') }), _jsx("button", { type: "button", className: "fx-ob-btn primary", onClick: next, children: isLast ? _jsxs(_Fragment, { children: [_jsx(Rocket, { size: 14 }), t('topbar.onboard.done')] }) : t('topbar.onboard.next') })] })] })] }), document.body);
+}

package/dist/package/browser/components/TopBar/SessionSwitcher.d.ts

@@ -0,0 +1,2 @@
+import './TopBar.css';
+export declare function SessionSwitcher(): import("react/jsx-runtime").JSX.Element;

package/dist/package/browser/components/TopBar/SessionSwitcher.js

@@ -0,0 +1,124 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SessionSwitcher — extracted from TopBar.tsx (§D). Reads store.tabs (the
+// single derived view of the server session list) so TopBar dropdown / TabStrip
+// never disagree. New/switch/close all go through the store actions.
+import { useState, useEffect } from 'react';
+import { History, ChevronDown, Plus, Trash2 } from 'lucide-react';
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover';
+import { t, useTranslation } from '../../i18n';
+import { tabLabel, useShellStore } from '../../store';
+import { confirmDialog } from '../../lib/dialog';
+import './TopBar.css';
+// 把 epoch-ms 渲染成相对/绝对时间标签。短窗口（<1h）走"X 分钟前"给手感
+// 强；当天走"HH:MM"；昨天 / 7 天内走"昨天 HH:MM" / "周X HH:MM"；再老就直
+// 接给日期 "MM-DD"。所有计算都在调用时拿 Date.now() 即时算，下拉每次开都
+// 重算，不需要 hook 心跳 —— 用户开-看-关的窗口里时间不会"卡"。
+function formatRelative(ts) {
+    if (!ts || !Number.isFinite(ts))
+        return '';
+    const now = Date.now();
+    const deltaMs = now - ts;
+    if (deltaMs < 0)
+        return t('sessionSwitcher.justNow'); // clock skew → treat as just now, not future
+    const sec = Math.floor(deltaMs / 1000);
+    if (sec < 60)
+        return t('sessionSwitcher.justNow');
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return t('sessionSwitcher.minutesAgo', { min });
+    // Compare calendar days using local-time midnight so "昨天" is intuitive
+    // across midnight rather than purely a 24-hour rolling window.
+    const tsDate = new Date(ts);
+    const nowDate = new Date(now);
+    const dayDiff = Math.floor((Date.UTC(nowDate.getFullYear(), nowDate.getMonth(), nowDate.getDate())
+        - Date.UTC(tsDate.getFullYear(), tsDate.getMonth(), tsDate.getDate()))
+        / 86_400_000);
+    const hh = String(tsDate.getHours()).padStart(2, '0');
+    const mm = String(tsDate.getMinutes()).padStart(2, '0');
+    if (dayDiff === 0)
+        return `${hh}:${mm}`;
+    if (dayDiff === 1)
+        return t('sessionSwitcher.yesterdayTime', { time: `${hh}:${mm}` });
+    if (dayDiff < 7)
+        return t('sessionSwitcher.daysAgo', { dayDiff });
+    // Older than a week — yyyy-mm-dd if cross-year, mm-dd otherwise.
+    const M = String(tsDate.getMonth() + 1).padStart(2, '0');
+    const D = String(tsDate.getDate()).padStart(2, '0');
+    return tsDate.getFullYear() === nowDate.getFullYear()
+        ? `${M}-${D}`
+        : `${tsDate.getFullYear()}-${M}-${D}`;
+}
+// R3 (2026-05-20 重做) —— SessionSwitcher 直接读 store.tabs（= server session
+// list 的派生 view）。不再独立维护 sessions[] state、不再调 GET /api/sessions：
+// 那一份 fetch 由 store.refreshSessions 统一管，保证 TopBar dropdown / TabStrip /
+// 任何其它 surface 永远看到同一份 sessions 数据 —— 即用户痛感「TopBar 显示 X
+// 但 TabStrip 显示 Y」根除。
+//
+// 操作语义：
+//   - 新建 session  → store.createNewSession()    （POST /api/sessions + tab）
+//   - 切 session   → store.switchToSession(sid)  （+ WS 重 attach + 持久化）
+//   - 删 session   → store.closeSession(sid)     （DELETE + 自动切下一条）
+export function SessionSwitcher() {
+    const { t } = useTranslation();
+    const [open, setOpen] = useState(false);
+    const activeGameSlug = useShellStore((s) => s.activeGameSlug);
+    const activeSid = useShellStore((s) => s.activeSid);
+    const tabs = useShellStore((s) => s.tabs);
+    const busyByAgentBySid = useShellStore((s) => s.busyByAgentBySid);
+    const createNewSession = useShellStore((s) => s.createNewSession);
+    const switchToSession = useShellStore((s) => s.switchToSession);
+    const closeSession = useShellStore((s) => s.closeSession);
+    const refreshSessions = useShellStore((s) => s.refreshSessions);
+    // Dropdown open / active game 变化时刷新一次 server list（防止外部进程直接
+    // 改了 ~/.forgeax/sessions/ 后 UI 看不到）。
+    useEffect(() => {
+        if (!open)
+            return;
+        void refreshSessions();
+    }, [open, activeGameSlug, refreshSessions]);
+    const onDelete = async (sid) => {
+        if (!(await confirmDialog({ body: t('sessionSwitcher.deleteConfirm'), danger: true })))
+            return;
+        await closeSession(sid);
+    };
+    const onPick = async (sid) => {
+        await switchToSession(sid);
+        setOpen(false);
+    };
+    const onNew = async () => {
+        const r = await createNewSession({ scope: activeGameSlug ?? undefined });
+        if (r)
+            setOpen(false);
+    };
+    const activeTab = tabs.find((t) => t.sid === activeSid);
+    const activeLabel = activeTab ? tabLabel(activeTab) : t('common.loading');
+    // Dropdown-only sort by最后对话时间 desc — keep store.tabs in its
+    // original order (TabStrip / persisted activeSid still index by it).
+    // Sessions without lastActivityAt sink to the bottom; among those, sid
+    // stable order. Fresh-created tabs (no on-disk activity yet) thus sit
+    // at the bottom until the next refresh populates the field, which feels
+    // wrong — bump them just-now (Date.now()) when the field is missing so
+    // a brand-new session appears at the top of the list immediately.
+    const now = Date.now();
+    const sortedTabs = [...tabs].sort((a, b) => {
+        const ta = a.lastActivityAt ?? now;
+        const tb = b.lastActivityAt ?? now;
+        return tb - ta;
+    });
+    return (_jsx(Popover, { open: open, onOpenChange: setOpen, children: _jsxs("div", { className: "tb-session-switcher", children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { className: "tb-game-btn", title: activeTab ? t('sessionSwitcher.triggerActive', { label: activeLabel }) : t('sessionSwitcher.triggerEmpty'), children: [_jsx(History, { size: 16 }), _jsx("span", { className: "tb-game-label", children: activeLabel }), _jsx(ChevronDown, { size: 16 })] }) }), _jsx(PopoverContent, { align: "start", sideOffset: 4, className: "w-auto border-0 bg-transparent p-0 shadow-none", children: _jsxs("div", { className: "tb-game-dropdown tb-game-dropdown--popover", style: { minWidth: 280 }, children: [_jsxs("button", { type: "button", className: "tb-game-pick", onClick: () => void onNew(), style: {
+                                    borderBottom: '1px solid var(--color-border-subtle)',
+                                    color: 'var(--color-role-art)',
+                                    /* dropdown 现在 max-height + 滚动,把 "+ 新建 session" 钉在顶部
+                                       不随列表滚走。top: -4px 抵消 dropdown 4px padding,贴齐边缘。 */
+                                    position: 'sticky',
+                                    top: -4,
+                                    background: 'var(--bg-2)',
+                                    zIndex: 1,
+                                }, title: t('sessionSwitcher.newSessionTitle'), children: [_jsx(Plus, { size: 12, style: { marginRight: 4 } }), _jsx("span", { className: "tb-game-name", children: t('sessionSwitcher.newSession') }), _jsx("span", { className: "tb-game-meta", children: activeGameSlug ? t('sessionSwitcher.projectBound', { slug: activeGameSlug }) : t('sessionSwitcher.projectUnbound') })] }), sortedTabs.length === 0 && (_jsx("div", { className: "tb-game-empty", children: t('sessionSwitcher.empty') })), sortedTabs.map((tab) => {
+                                const isActive = tab.sid === activeSid;
+                                const label = tabLabel(tab);
+                                const rel = formatRelative(tab.lastActivityAt);
+                                const isBusy = Object.values(busyByAgentBySid[tab.sid] ?? {}).some(Boolean);
+                                return (_jsxs("div", { className: `tb-game-row ${isActive ? 'is-active' : ''}`, "data-session-id": tab.sid, "data-session-name": label, children: [_jsxs("button", { className: "tb-game-pick", onClick: () => void onPick(tab.sid), title: `sid: ${tab.sid}${tab.agentId ? ` · agent: ${tab.agentId}` : ''}${tab.lastActivityAt ? ` · ${t('sessionSwitcher.lastActive', { time: new Date(tab.lastActivityAt).toLocaleString() })}` : ''}`, children: [_jsxs("span", { className: "tb-game-name", children: [label, isActive && _jsx("span", { style: { marginLeft: 6, color: 'var(--color-role-art)' }, children: "\u00B7" })] }), _jsxs("span", { className: "tb-game-meta", children: [tab.sid.slice(0, 8), tab.agentId ? ` · ${tab.agentId}` : '', isBusy ? ' · ●' : '', rel ? ` · ${rel}` : ''] })] }), _jsx("button", { className: "tb-game-del", onClick: () => void onDelete(tab.sid), title: t('sessionSwitcher.deleteTitle'), children: _jsx(Trash2, { size: 11 }) })] }, tab.sid));
+                            })] }) })] }) }));
+}