@forgeax/interface 0.4.1

package/dist/package/browser/store-parts/persistence.d.ts

@@ -0,0 +1,40 @@
+export type DurablePersistenceState = 'dirty' | 'clean' | 'unknown';
+export interface FreshReaderRealm<T> {
+    readonly realmId: string;
+    readonly read: () => Promise<T>;
+}
+export interface DurableSaveVerification<T> {
+    readonly requestId: string;
+    readonly state: DurablePersistenceState;
+    readonly writerRealmId: string;
+    readonly readerRealmId: string | null;
+    readonly authoritative: T | null;
+    readonly observed: T | null;
+    readonly error?: {
+        readonly code: 'invalid-request' | 'save-failed' | 'reader-not-independent' | 'read-back-failed' | 'durability-mismatch';
+        readonly hint: string;
+        readonly retryable: boolean;
+        readonly recoveryActions: readonly string[];
+    };
+}
+export declare function verifyDurableSave<T>(input: {
+    readonly requestId: string;
+    readonly writerRealmId: string;
+    readonly authoritative: T;
+    readonly createFreshReader: () => Promise<FreshReaderRealm<T>>;
+}): Promise<DurableSaveVerification<T>>;
+export declare function saveAndVerifyDurably<T>(input: {
+    readonly requestId: string;
+    readonly writerRealmId: string;
+    readonly save: () => Promise<T>;
+    readonly createFreshReader: () => Promise<FreshReaderRealm<T>>;
+}): Promise<DurableSaveVerification<T>>;
+export declare function loadProviderOverride(): string | null;
+export declare function saveProviderOverride(id: string | null): void;
+export declare function loadSettingsSection(): string | null;
+export declare function saveSettingsSection(id: string | null): void;
+export declare function cleanupLegacySessionKeys(): void;
+export declare function loadAgentBySid(): Record<string, string>;
+export declare function persistAgentBySid(map: Record<string, string>): void;
+export declare function loadActiveSid(): string | null;
+export declare function persistActiveSid(sid: string | null): void;

package/dist/package/browser/store-parts/persistence.js

@@ -0,0 +1,245 @@
+const PROVIDER_OVERRIDE_KEY = 'forgeax.providerOverride';
+const SETTINGS_SECTION_KEY = 'forgeax.settingsSection';
+const ACTIVE_SID_KEY = 'forgeax.activeSid';
+const AGENT_BY_SID_KEY = 'forgeax.agentBySid';
+const LEGACY_TABS_KEY = 'forgeax.tabs';
+const LEGACY_ACTIVE_TAB_KEY = 'forgeax.activeTabId';
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, stableValue(entry)]));
+    }
+    return value;
+}
+function equalDurableValue(left, right) {
+    return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
+}
+export async function verifyDurableSave(input) {
+    const base = {
+        requestId: input.requestId,
+        writerRealmId: input.writerRealmId,
+        authoritative: input.authoritative,
+    };
+    if (!input.requestId.trim() || !input.writerRealmId.trim()) {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: null,
+            observed: null,
+            error: {
+                code: 'invalid-request',
+                hint: 'Save verification requires a requestId and writer realm identity.',
+                retryable: false,
+                recoveryActions: ['persistence.discover', 'persistence.retry'],
+            },
+        };
+    }
+    let reader;
+    try {
+        reader = await input.createFreshReader();
+    }
+    catch {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: null,
+            observed: null,
+            error: {
+                code: 'read-back-failed',
+                hint: 'The independent reader could not be created; durability is unknown.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    if (!reader.realmId.trim() || reader.realmId === input.writerRealmId) {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: reader.realmId || null,
+            observed: null,
+            error: {
+                code: 'reader-not-independent',
+                hint: 'Durability requires a newly created reader realm distinct from the writer.',
+                retryable: false,
+                recoveryActions: ['persistence.discover', 'persistence.retry'],
+            },
+        };
+    }
+    let observed;
+    try {
+        observed = await reader.read();
+    }
+    catch {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: reader.realmId,
+            observed: null,
+            error: {
+                code: 'read-back-failed',
+                hint: 'The independent reader failed to read the authoritative value; durability is unknown.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    if (!equalDurableValue(input.authoritative, observed)) {
+        return {
+            ...base,
+            state: 'dirty',
+            readerRealmId: reader.realmId,
+            observed,
+            error: {
+                code: 'durability-mismatch',
+                hint: 'The fresh reader observed a different authoritative value; the save is not clean.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    return {
+        ...base,
+        state: 'clean',
+        readerRealmId: reader.realmId,
+        observed,
+    };
+}
+export async function saveAndVerifyDurably(input) {
+    if (!input.requestId.trim() || !input.writerRealmId.trim())
+        return {
+            requestId: input.requestId,
+            writerRealmId: input.writerRealmId,
+            state: 'unknown',
+            readerRealmId: null,
+            authoritative: null,
+            observed: null,
+            error: {
+                code: 'invalid-request',
+                hint: 'Save requires a requestId and writer realm identity.',
+                retryable: false,
+                recoveryActions: ['persistence.discover', 'persistence.retry'],
+            },
+        };
+    let authoritative;
+    try {
+        authoritative = await input.save();
+    }
+    catch {
+        return {
+            requestId: input.requestId,
+            writerRealmId: input.writerRealmId,
+            state: 'unknown',
+            readerRealmId: null,
+            authoritative: null,
+            observed: null,
+            error: {
+                code: 'save-failed',
+                hint: 'The authoritative Host save failed; the durable state is unknown.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    return verifyDurableSave({ ...input, authoritative });
+}
+export function loadProviderOverride() {
+    try {
+        const v = localStorage.getItem(PROVIDER_OVERRIDE_KEY);
+        return v && v !== 'null' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveProviderOverride(id) {
+    try {
+        if (id === null)
+            localStorage.removeItem(PROVIDER_OVERRIDE_KEY);
+        else
+            localStorage.setItem(PROVIDER_OVERRIDE_KEY, id);
+    }
+    catch {
+        /* ignore (private mode / SSR) */
+    }
+}
+export function loadSettingsSection() {
+    try {
+        const v = localStorage.getItem(SETTINGS_SECTION_KEY);
+        return v && v.trim() ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSettingsSection(id) {
+    try {
+        if (id)
+            localStorage.setItem(SETTINGS_SECTION_KEY, id);
+        else
+            localStorage.removeItem(SETTINGS_SECTION_KEY);
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function cleanupLegacySessionKeys() {
+    try {
+        localStorage.removeItem(LEGACY_TABS_KEY);
+        localStorage.removeItem(LEGACY_ACTIVE_TAB_KEY);
+    }
+    catch {
+        /* ignore (private mode / SSR) */
+    }
+}
+export function loadAgentBySid() {
+    try {
+        const raw = localStorage.getItem(AGENT_BY_SID_KEY);
+        if (!raw)
+            return {};
+        const obj = JSON.parse(raw);
+        if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+            return {};
+        const out = {};
+        for (const [sid, agent] of Object.entries(obj)) {
+            if (typeof sid === 'string' && typeof agent === 'string' && sid && agent) {
+                out[sid] = agent;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function persistAgentBySid(map) {
+    try {
+        localStorage.setItem(AGENT_BY_SID_KEY, JSON.stringify(map));
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function loadActiveSid() {
+    try {
+        const v = localStorage.getItem(ACTIVE_SID_KEY);
+        return v && v.trim() ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function persistActiveSid(sid) {
+    try {
+        if (sid)
+            localStorage.setItem(ACTIVE_SID_KEY, sid);
+        else
+            localStorage.removeItem(ACTIVE_SID_KEY);
+    }
+    catch {
+        /* ignore */
+    }
+}

package/dist/package/browser/store-parts/session-client.d.ts

@@ -0,0 +1,73 @@
+export interface SessionMeta {
+    sid: string;
+    displayName?: string;
+    defaultDir?: string;
+    autoStart?: boolean;
+    lastActivityAt?: number;
+}
+export interface ForgeaXAgentNode {
+    path: string;
+    display: string;
+    depth: number;
+    fullId: string;
+    parent: string | null;
+    hasLedger: boolean;
+    running: boolean;
+}
+export interface SessionEvent {
+    type: 'session-event';
+    sid: string;
+    emitterId?: string;
+    event: {
+        source: string;
+        type: string;
+        payload: Record<string, unknown>;
+        to?: string;
+        ts: number;
+    };
+}
+export type SessionEventHandler = (event: SessionEvent) => void;
+export interface SessionClient {
+    fetchSessionList: (game?: string) => Promise<SessionMeta[]>;
+    createSession: (opts?: {
+        displayName?: string;
+        scope?: string;
+        autoStart?: boolean;
+        bootstrapAgent?: string | false | null;
+    }) => Promise<{
+        sid: string;
+        bootstrappedAgent: string | null;
+    }>;
+    ensureSession: (opts?: {
+        scope?: string;
+        autoStart?: boolean;
+        bootstrapAgent?: string | false | null;
+    }) => Promise<{
+        sid: string;
+        bootstrappedAgent: string | null;
+        created: boolean;
+    }>;
+    deleteSession: (sid: string) => Promise<void>;
+    emitForgeaXMessage: (sid: string, content: string, opts?: {
+        to?: string;
+        type?: string;
+        payload?: Record<string, unknown>;
+        handoff?: 'silent' | 'passive' | 'turn' | 'innerLoop' | 'steer';
+    }) => Promise<{
+        ok: boolean;
+        to?: string;
+        msgId?: string;
+        error?: string;
+    }>;
+    listSessionAgents: (sid: string) => Promise<ForgeaXAgentNode[]>;
+    connectForgeaXWs: (sid: string | null) => void;
+    disconnectForgeaXWs: () => void;
+    onSessionEvent: (key: string, handler: SessionEventHandler) => () => void;
+}
+export declare function configureSessionClient(client: SessionClient): void;
+/** True once the composition root injected a client. Lets optional consumers
+ *  (session-client plugin) degrade gracefully instead of hitting the
+ *  getSessionClient() throw — interface-alone / standalone-editor hosts have
+ *  no forgeax-server and never configure one. */
+export declare function hasSessionClient(): boolean;
+export declare function getSessionClient(): SessionClient;

package/dist/package/browser/store-parts/session-client.js

@@ -0,0 +1,17 @@
+let configuredClient = null;
+export function configureSessionClient(client) {
+    configuredClient = client;
+}
+/** True once the composition root injected a client. Lets optional consumers
+ *  (session-client plugin) degrade gracefully instead of hitting the
+ *  getSessionClient() throw — interface-alone / standalone-editor hosts have
+ *  no forgeax-server and never configure one. */
+export function hasSessionClient() {
+    return configuredClient !== null;
+}
+export function getSessionClient() {
+    if (!configuredClient) {
+        throw new Error('No session client configured. The Studio composition root must inject one before booting interface.');
+    }
+    return configuredClient;
+}

package/dist/package/browser/store-parts/session-pick.d.ts

@@ -0,0 +1,8 @@
+export interface PickableSession {
+    sid: string;
+    lastActivityAt?: number;
+}
+/** 该 game 最近活跃的一条会话 sid；空列表 → null。 */
+export declare function mostRecentSid(tabs: readonly PickableSession[]): string | null;
+/** persisted sid 仍在列表里 → 尊重用户上次的停留；否则回落最近活跃。 */
+export declare function pickActiveSid(tabs: readonly PickableSession[], persisted: string | null): string | null;

package/dist/package/browser/store-parts/session-pick.js

@@ -0,0 +1,21 @@
+// 会话回落挑选规则（SSOT）—— initSessions / refreshSessions / setActiveGame 共用。
+//
+// 历史与 game 绑定：刷新 / 切 game / 列表变更后，UI 应回到「上次明确停留的那条
+// 会话（persisted sid，若仍存在）」，否则回到「该 game 最近活跃的一条」。server
+// 的 /api/sessions 不保证按活跃度排序，所以这里显式按 lastActivityAt 挑，
+// 而不是拿列表第 0 位。
+/** 该 game 最近活跃的一条会话 sid；空列表 → null。 */
+export function mostRecentSid(tabs) {
+    let best = null;
+    for (const t of tabs) {
+        if (!best || (t.lastActivityAt ?? 0) > (best.lastActivityAt ?? 0))
+            best = t;
+    }
+    return best?.sid ?? null;
+}
+/** persisted sid 仍在列表里 → 尊重用户上次的停留；否则回落最近活跃。 */
+export function pickActiveSid(tabs, persisted) {
+    if (persisted && tabs.some((t) => t.sid === persisted))
+        return persisted;
+    return mostRecentSid(tabs);
+}

package/dist/package/browser/store-parts/shell.d.ts

@@ -0,0 +1,5 @@
+import type { AppState } from '../store';
+type SetAppState = (partial: Partial<AppState> | ((state: AppState) => Partial<AppState>)) => void;
+type GetAppState = () => AppState;
+export declare function createShellState(set: SetAppState, get: GetAppState): Pick<AppState, 'detachSurface' | 'redockSurface' | 'activeSession' | 'setActiveSession' | 'activeOverlay' | 'overlayParam' | 'openOverlay' | 'setOverlayParam' | 'closeOverlay' | 'gameDirectoryModalOpen' | 'openGameDirectoryModal' | 'closeGameDirectoryModal' | 'gameSwitcherOpen' | 'setGameSwitcherOpen' | 'gameModalOpen' | 'openGameModal' | 'closeGameModal' | 'fullscreen' | 'setFullscreen' | 'toggleFullscreen' | 'sidebarCollapsed' | 'chatpanelCollapsed' | 'toggleSidebar' | 'toggleChatpanel'>;
+export {};

package/dist/package/browser/store-parts/shell.js

@@ -0,0 +1,37 @@
+import { getSurfaceWindowingController } from '../lib/platform';
+import { loadSettingsSection, saveSettingsSection } from './persistence';
+export function createShellState(set, get) {
+    return {
+        detachSurface: (d, opts) => getSurfaceWindowingController().detachSurface(d, opts),
+        redockSurface: (d) => getSurfaceWindowingController().redockSurface(d),
+        activeSession: 'main-design',
+        setActiveSession: (s) => set({ activeSession: s }),
+        activeOverlay: null,
+        overlayParam: loadSettingsSection(),
+        openOverlay: (id, param) => {
+            const p = param ?? get().overlayParam ?? null;
+            saveSettingsSection(p);
+            set({ activeOverlay: id, overlayParam: p });
+        },
+        setOverlayParam: (param) => {
+            saveSettingsSection(param);
+            set({ overlayParam: param });
+        },
+        closeOverlay: () => set({ activeOverlay: null }),
+        gameDirectoryModalOpen: false,
+        openGameDirectoryModal: () => set({ gameDirectoryModalOpen: true }),
+        closeGameDirectoryModal: () => set({ gameDirectoryModalOpen: false }),
+        gameSwitcherOpen: false,
+        setGameSwitcherOpen: (v) => set({ gameSwitcherOpen: v }),
+        gameModalOpen: false,
+        openGameModal: () => set({ gameModalOpen: true }),
+        closeGameModal: () => set({ gameModalOpen: false }),
+        fullscreen: false,
+        setFullscreen: (v) => set({ fullscreen: v }),
+        toggleFullscreen: () => set((s) => ({ fullscreen: !s.fullscreen })),
+        sidebarCollapsed: false,
+        chatpanelCollapsed: false,
+        toggleSidebar: () => set((s) => ({ sidebarCollapsed: !s.sidebarCollapsed })),
+        toggleChatpanel: () => set((s) => ({ chatpanelCollapsed: !s.chatpanelCollapsed })),
+    };
+}