@forgeax/interface 0.4.1

package/dist/package/browser/boot/driver.js

@@ -0,0 +1,47 @@
+/**
+ * Boot driver — the React-side half of the boot splash handshake.
+ *
+ * The inline bootstrap in index.html exposes `window.__forgeaxBoot` with two
+ * methods: `progress({pct, label})` and `done()`. While React is mounting we
+ * call these to drive the visible progress bar; after the first paint we
+ * fire `done()` so the splash fades out and the studio takes over.
+ *
+ * The contract is one-way and lossy: missing window.__forgeaxBoot (e.g. user
+ * loaded a stripped index.html) is silently ignored — the studio still works,
+ * just without splash control.
+ */
+function bootApi() {
+    if (typeof window === 'undefined')
+        return null;
+    return window.__forgeaxBoot ?? null;
+}
+/**
+ * Called at the top of main.tsx (before createRoot.render) to mark "JS is
+ * executing, React is about to mount".
+ */
+export function bootStageEntry() {
+    bootApi()?.progress({ pct: 60, label: 'mounting shell' });
+}
+/**
+ * Called from <App/>'s first useEffect to mark "React tree is wired and
+ * client-side effects are firing". One rAF later we declare done().
+ */
+export function bootStageAppMounted() {
+    const api = bootApi();
+    if (!api)
+        return;
+    api.progress({ pct: 92, label: 'wiring panels' });
+    // Wait for the first composited paint so the splash fade lines up with
+    // the real studio appearing underneath — otherwise the player sees a
+    // brief blank flash.
+    if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function') {
+        api.done();
+        return;
+    }
+    window.requestAnimationFrame(() => {
+        window.requestAnimationFrame(() => {
+            api.progress({ pct: 100, label: 'ready' });
+            api.done();
+        });
+    });
+}

package/dist/package/browser/boot/store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Boot splash config store.
+ *
+ * Source of truth lives in two places:
+ *  - localStorage `forgeax.boot.splash.v1` — read synchronously by the inline
+ *    bootstrap in index.html BEFORE React mounts, so the chosen theme paints
+ *    on the first frame.
+ *  - `<projectRoot>/.forgeax/boot-splash.json` — persisted server-side so AI
+ *    in ChatPanel can `curl POST /api/boot-splash` and the change carries
+ *    across browsers / clean localStorage.
+ *
+ * On Settings panel mount we GET /api/boot-splash and reconcile to localStorage
+ * (server wins). On any save in Settings we write localStorage AND POST to the
+ * server. The inline bootstrap only ever reads localStorage — server fetch
+ * during boot is too slow.
+ */
+import { type SplashConfig } from './types';
+export declare const bootSplashStore: {
+    get(): SplashConfig;
+    set(next: SplashConfig): void;
+    subscribe(fn: () => void): () => void;
+};
+/**
+ * React hook exposing the current splash config + a setter. Setter writes
+ * localStorage immediately AND fires a POST to /api/boot-splash so AI's
+ * server-side view stays in sync. Server failure is silent — the user can
+ * still iterate locally; AI just won't see the change until next save.
+ */
+export declare function useSplashConfig(): [SplashConfig, (next: SplashConfig) => void];

package/dist/package/browser/boot/store.js

@@ -0,0 +1,114 @@
+/**
+ * Boot splash config store.
+ *
+ * Source of truth lives in two places:
+ *  - localStorage `forgeax.boot.splash.v1` — read synchronously by the inline
+ *    bootstrap in index.html BEFORE React mounts, so the chosen theme paints
+ *    on the first frame.
+ *  - `<projectRoot>/.forgeax/boot-splash.json` — persisted server-side so AI
+ *    in ChatPanel can `curl POST /api/boot-splash` and the change carries
+ *    across browsers / clean localStorage.
+ *
+ * On Settings panel mount we GET /api/boot-splash and reconcile to localStorage
+ * (server wins). On any save in Settings we write localStorage AND POST to the
+ * server. The inline bootstrap only ever reads localStorage — server fetch
+ * during boot is too slow.
+ */
+import { useEffect, useSyncExternalStore } from 'react';
+import { DEFAULT_SPLASH, SPLASH_STORAGE_KEY, isValidSplashConfig, } from './types';
+let cached = DEFAULT_SPLASH;
+let initialized = false;
+const listeners = new Set();
+function readLocal() {
+    if (typeof window === 'undefined')
+        return DEFAULT_SPLASH;
+    try {
+        const raw = window.localStorage.getItem(SPLASH_STORAGE_KEY);
+        if (!raw)
+            return DEFAULT_SPLASH;
+        const parsed = JSON.parse(raw);
+        return isValidSplashConfig(parsed) ? parsed : DEFAULT_SPLASH;
+    }
+    catch {
+        return DEFAULT_SPLASH;
+    }
+}
+function writeLocal(c) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(SPLASH_STORAGE_KEY, JSON.stringify(c));
+    }
+    catch {
+        /* localStorage may throw in privacy mode — silently ignore, server still holds the truth */
+    }
+}
+function emit() {
+    for (const fn of listeners)
+        fn();
+}
+function ensureInit() {
+    if (initialized)
+        return;
+    initialized = true;
+    cached = readLocal();
+}
+export const bootSplashStore = {
+    get() {
+        ensureInit();
+        return cached;
+    },
+    set(next) {
+        ensureInit();
+        cached = next;
+        writeLocal(next);
+        emit();
+    },
+    subscribe(fn) {
+        listeners.add(fn);
+        return () => {
+            listeners.delete(fn);
+        };
+    },
+};
+/**
+ * React hook exposing the current splash config + a setter. Setter writes
+ * localStorage immediately AND fires a POST to /api/boot-splash so AI's
+ * server-side view stays in sync. Server failure is silent — the user can
+ * still iterate locally; AI just won't see the change until next save.
+ */
+export function useSplashConfig() {
+    const value = useSyncExternalStore(bootSplashStore.subscribe, bootSplashStore.get, bootSplashStore.get);
+    // On first mount, reconcile from server (server wins if it has a saved file).
+    useEffect(() => {
+        let cancelled = false;
+        void (async () => {
+            try {
+                const r = await fetch('/api/boot-splash');
+                if (!r.ok)
+                    return;
+                const j = (await r.json());
+                if (cancelled)
+                    return;
+                if (j.config && isValidSplashConfig(j.config)) {
+                    bootSplashStore.set(j.config);
+                }
+            }
+            catch {
+                /* server down — keep local copy */
+            }
+        })();
+        return () => { cancelled = true; };
+    }, []);
+    const setter = (next) => {
+        bootSplashStore.set(next);
+        // Fire-and-forget server save. AI reads from the same endpoint, so this
+        // keeps server side in sync. Errors don't block the UI.
+        void fetch('/api/boot-splash', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(next),
+        }).catch(() => { });
+    };
+    return [value, setter];
+}

package/dist/package/browser/boot/themes.d.ts

@@ -0,0 +1,19 @@
+import type { SplashThemeId } from './types';
+/**
+ * Theme registry — keep this list in sync with the CSS classes in index.html
+ * (`.fgx-boot.t-classic-lime`, `.fgx-boot.t-neon-pulse`). Adding a third theme
+ * is one entry here + one CSS block there + one option in SettingsSection.
+ */
+export interface SplashTheme {
+    id: SplashThemeId;
+    label: string;
+    /** i18n key for `label` (namespace `themes.`); consumer may call t(labelKey). */
+    labelKey: string;
+    /** Hex used by SettingsSection's preview swatch. */
+    swatch: string;
+    desc: string;
+    /** i18n key for `desc` (namespace `themes.`); consumer may call t(descKey). */
+    descKey: string;
+}
+export declare const SPLASH_THEMES: SplashTheme[];
+export declare function themeById(id: SplashThemeId): SplashTheme;

package/dist/package/browser/boot/themes.js

@@ -0,0 +1,21 @@
+export const SPLASH_THEMES = [
+    {
+        id: 'classic-lime',
+        label: 'Classic Lime',
+        labelKey: 'themes.classicLime.label',
+        swatch: '#d4ff48',
+        desc: 'Current style · lime accent + horizontal progress bar',
+        descKey: 'themes.classicLime.desc',
+    },
+    {
+        id: 'neon-pulse',
+        label: 'Neon Pulse',
+        labelKey: 'themes.neonPulse.label',
+        swatch: '#7dd3fc',
+        desc: 'Radial pulse animation + full-screen logo + arc progress bar',
+        descKey: 'themes.neonPulse.desc',
+    },
+];
+export function themeById(id) {
+    return SPLASH_THEMES.find((t) => t.id === id) ?? SPLASH_THEMES[0];
+}

package/dist/package/browser/boot/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Boot splash config — small enough to live in localStorage AND server-side
+ * `.forgeax/boot-splash.json`. Schema versioned so future fields don't break
+ * older saves (load() drops anything with `v !== current` back to defaults).
+ *
+ * The inline splash bootstrap in `index.html` reads the localStorage entry
+ * BEFORE React loads, so this shape must stay JSON-serializable and free of
+ * any TS-side dependencies.
+ */
+export declare const SPLASH_SCHEMA_VERSION: 1;
+export type SplashThemeId = 'classic-lime' | 'neon-pulse';
+export interface SplashConfig {
+    v: typeof SPLASH_SCHEMA_VERSION;
+    theme: SplashThemeId;
+    title: string;
+    subtitle: string;
+    showProgressBar: boolean;
+    showBusInventory: boolean;
+}
+export declare const DEFAULT_SPLASH: SplashConfig;
+export declare const SPLASH_STORAGE_KEY = "forgeax.boot.splash.v1";
+export declare function isValidSplashConfig(x: unknown): x is SplashConfig;

package/dist/package/browser/boot/types.js

@@ -0,0 +1,30 @@
+/**
+ * Boot splash config — small enough to live in localStorage AND server-side
+ * `.forgeax/boot-splash.json`. Schema versioned so future fields don't break
+ * older saves (load() drops anything with `v !== current` back to defaults).
+ *
+ * The inline splash bootstrap in `index.html` reads the localStorage entry
+ * BEFORE React loads, so this shape must stay JSON-serializable and free of
+ * any TS-side dependencies.
+ */
+export const SPLASH_SCHEMA_VERSION = 1;
+export const DEFAULT_SPLASH = {
+    v: SPLASH_SCHEMA_VERSION,
+    theme: 'classic-lime',
+    title: 'forgeax · Studio',
+    subtitle: 'booting shell…',
+    showProgressBar: true,
+    showBusInventory: false,
+};
+export const SPLASH_STORAGE_KEY = 'forgeax.boot.splash.v1';
+export function isValidSplashConfig(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const o = x;
+    return (o.v === SPLASH_SCHEMA_VERSION &&
+        (o.theme === 'classic-lime' || o.theme === 'neon-pulse') &&
+        typeof o.title === 'string' &&
+        typeof o.subtitle === 'string' &&
+        typeof o.showProgressBar === 'boolean' &&
+        typeof o.showBusInventory === 'boolean');
+}

package/dist/package/browser/brand/BrandProvider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BrandProvider + useBrand — React-side brand pack consumer.
+ *
+ * Wraps the app in main.tsx. Inside the tree, call `useBrand()` to read the
+ * active pack synchronously. Code outside React (module scope, store, vite
+ * plugin) should call `getBrandSync()` from ./runtime instead.
+ *
+ * The provider trusts `window.__BRAND__` (injected by vite-plugin-brand at
+ * dev/build time). It does not fetch /api/brand — the inline injection is
+ * synchronous and avoids a flash of un-branded content.
+ */
+import type { ReactNode } from 'react';
+import type { BrandConfig, BrandRuntime } from './types';
+export declare function BrandProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useBrand(): BrandConfig;
+export declare function useBrandRuntime(): BrandRuntime;
+export declare function useBrandAsset(key: 'favicon' | 'logo' | 'avatar'): string | null;

package/dist/package/browser/brand/BrandProvider.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * BrandProvider + useBrand — React-side brand pack consumer.
+ *
+ * Wraps the app in main.tsx. Inside the tree, call `useBrand()` to read the
+ * active pack synchronously. Code outside React (module scope, store, vite
+ * plugin) should call `getBrandSync()` from ./runtime instead.
+ *
+ * The provider trusts `window.__BRAND__` (injected by vite-plugin-brand at
+ * dev/build time). It does not fetch /api/brand — the inline injection is
+ * synchronous and avoids a flash of un-branded content.
+ */
+import { createContext, useContext, useMemo } from 'react';
+import { getBrandRuntimeSync, getBrandAssetUrl } from './runtime';
+const BrandContext = createContext(null);
+export function BrandProvider({ children }) {
+    const value = useMemo(() => getBrandRuntimeSync(), []);
+    return _jsx(BrandContext.Provider, { value: value, children: children });
+}
+export function useBrand() {
+    const ctx = useContext(BrandContext);
+    if (ctx)
+        return ctx.config;
+    return getBrandRuntimeSync().config;
+}
+export function useBrandRuntime() {
+    const ctx = useContext(BrandContext);
+    if (ctx)
+        return ctx;
+    return getBrandRuntimeSync();
+}
+export function useBrandAsset(key) {
+    // Re-derive on every render; getBrandAssetUrl is pure and cheap.
+    return getBrandAssetUrl(key);
+}

package/dist/package/browser/brand/index.d.ts

@@ -0,0 +1,4 @@
+export { BrandProvider, useBrand, useBrandRuntime, useBrandAsset } from './BrandProvider';
+export { getBrandSync, getBrandRuntimeSync, getBrandAssetUrl } from './runtime';
+export type { BrandConfig, BrandRuntime, BrandSource, SplashThemeId } from './types';
+export { BRAND_SCHEMA_VERSION } from './types';

package/dist/package/browser/brand/index.js

@@ -0,0 +1,3 @@
+export { BrandProvider, useBrand, useBrandRuntime, useBrandAsset } from './BrandProvider';
+export { getBrandSync, getBrandRuntimeSync, getBrandAssetUrl } from './runtime';
+export { BRAND_SCHEMA_VERSION } from './types';

package/dist/package/browser/brand/runtime.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Module-scope brand runtime.
+ *
+ * The vite plugin injects `window.__BRAND__` inline in `index.html` BEFORE
+ * the `main.tsx` module fetch starts, so `getBrandSync()` remains safe for
+ * early module callers.
+ *
+ * If `window.__BRAND__` is missing (e.g. the user stripped the inline script,
+ * or unit tests), `getBrandSync()` falls back to a hard-coded ForgeaX stub so
+ * UI code never throws. The fallback intentionally mirrors
+ * `brand/defaults.forgeax.json` — keep it in sync if you ever change the
+ * canonical defaults.
+ */
+import type { BrandConfig, BrandRuntime } from './types';
+export declare function getBrandRuntimeSync(): BrandRuntime;
+export declare function getBrandSync(): BrandConfig;
+export declare function getBrandAssetUrl(asset: 'favicon' | 'logo' | 'avatar'): string | null;

package/dist/package/browser/brand/runtime.js

@@ -0,0 +1,71 @@
+/**
+ * Module-scope brand runtime.
+ *
+ * The vite plugin injects `window.__BRAND__` inline in `index.html` BEFORE
+ * the `main.tsx` module fetch starts, so `getBrandSync()` remains safe for
+ * early module callers.
+ *
+ * If `window.__BRAND__` is missing (e.g. the user stripped the inline script,
+ * or unit tests), `getBrandSync()` falls back to a hard-coded ForgeaX stub so
+ * UI code never throws. The fallback intentionally mirrors
+ * `brand/defaults.forgeax.json` — keep it in sync if you ever change the
+ * canonical defaults.
+ */
+const FALLBACK = {
+    id: 'forgeax',
+    schemaVersion: 1,
+    product: {
+        name: 'ForgeaX Studio',
+        shortName: 'forgeax',
+        tagline: 'AI-first game dev shell — open desktop edition',
+    },
+    assistant: {
+        name: 'Forge',
+        avatarSrc: null,
+        cardName: { zh: '主线制作人', en: 'Lead Producer' },
+    },
+    splash: {
+        title: 'ForgeaX · Studio',
+        subtitle: 'booting shell…',
+        theme: 'classic-lime',
+    },
+    providers: {
+        native: { id: 'forgeax', label: 'forgeax', title: 'ForgeaX native CLI provider' },
+    },
+    links: {
+        repoUrl: 'https://github.com/ForgeaXGame/forgeax-studio',
+        communityUrl: 'https://forge.games',
+    },
+    assets: {
+        favicon: 'assets/favicon.svg',
+        logo: 'assets/logo.svg',
+    },
+};
+const FALLBACK_RUNTIME = {
+    config: FALLBACK,
+    source: { kind: 'default' },
+    assetBaseUrl: '/brand/',
+};
+export function getBrandRuntimeSync() {
+    if (typeof window !== 'undefined' && window.__BRAND__) {
+        return window.__BRAND__;
+    }
+    return FALLBACK_RUNTIME;
+}
+export function getBrandSync() {
+    return getBrandRuntimeSync().config;
+}
+export function getBrandAssetUrl(asset) {
+    const rt = getBrandRuntimeSync();
+    const map = {
+        favicon: rt.config.assets?.favicon,
+        logo: rt.config.assets?.logo,
+        avatar: rt.config.assistant.avatarSrc,
+    };
+    const rel = map[asset];
+    if (!rel)
+        return null;
+    // assets is published under `<base>/<asset-relative>` by the vite plugin.
+    const base = rt.assetBaseUrl.endsWith('/') ? rt.assetBaseUrl : `${rt.assetBaseUrl}/`;
+    return `${base}${rel.replace(/^\.?\/+/, '')}`;
+}

package/dist/package/browser/brand/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Brand pack — interface-side type mirror.
+ *
+ * Structurally identical to `packages/server/src/brand/types.ts`. Kept as a
+ * standalone copy because vite + react interface is a separate package and
+ * does not depend on server. If you change a field, update both files (and
+ * `brand/schema.json` + `brand/defaults.forgeax.json`).
+ */
+export declare const BRAND_SCHEMA_VERSION: 1;
+export type SplashThemeId = 'classic-lime' | 'neon-pulse';
+export interface BrandConfig {
+    id: string;
+    schemaVersion: typeof BRAND_SCHEMA_VERSION;
+    product: {
+        name: string;
+        shortName: string;
+        tagline: string;
+    };
+    assistant: {
+        name: string;
+        avatarSrc?: string | null;
+        personaOverride?: {
+            zh?: string | null;
+            en?: string | null;
+        };
+        cardName?: {
+            zh?: string;
+            en?: string;
+        };
+    };
+    splash: {
+        title: string;
+        subtitle: string;
+        theme: SplashThemeId;
+    };
+    providers: {
+        native: {
+            id: string;
+            label: string;
+            title: string;
+        };
+    };
+    links: {
+        repoUrl: string;
+        communityUrl: string;
+        docsUrl?: string | null;
+        issuesUrl?: string | null;
+    };
+    assets?: {
+        favicon?: string | null;
+        logo?: string | null;
+        appleTouchIcon?: string | null;
+    };
+}
+export type BrandSource = {
+    kind: 'env';
+    name: string;
+} | {
+    kind: 'symlink';
+    target: string;
+} | {
+    kind: 'default';
+} | {
+    kind: 'override-dir';
+    dir: string;
+};
+export interface BrandRuntime {
+    config: BrandConfig;
+    source: BrandSource;
+    /** URL prefix served by vite (dev) / the server (`/brand/assets/` proxy). */
+    assetBaseUrl: string;
+}
+declare global {
+    interface Window {
+        __BRAND__?: BrandRuntime;
+    }
+}

package/dist/package/browser/brand/types.js

@@ -0,0 +1,9 @@
+/**
+ * Brand pack — interface-side type mirror.
+ *
+ * Structurally identical to `packages/server/src/brand/types.ts`. Kept as a
+ * standalone copy because vite + react interface is a separate package and
+ * does not depend on server. If you change a field, update both files (and
+ * `brand/schema.json` + `brand/defaults.forgeax.json`).
+ */
+export const BRAND_SCHEMA_VERSION = 1;