@forgeax/interface 0.4.1

package/dist/package/browser/lib/useConfirmToast.d.ts

@@ -0,0 +1,26 @@
+export interface ConfirmCaller {
+    kind: string;
+    threadId?: string;
+    [key: string]: unknown;
+}
+export interface ConfirmPayload {
+    toolId: string;
+    token: string;
+    caller: ConfirmCaller;
+    reason?: string;
+    message?: string;
+}
+export interface PendingConfirm extends ConfirmPayload {
+    receivedAt: number;
+}
+/**
+ * Parse a raw SSE data string as a tool.confirm-required envelope.
+ * Returns the inner ConfirmPayload, or null if the envelope does not match.
+ */
+export declare function parseConfirmEnvelope(raw: string): ConfirmPayload | null;
+export interface UseConfirmToastResult {
+    pendingConfirms: PendingConfirm[];
+    ack: (token: string) => Promise<void>;
+    deny: (token: string) => Promise<void>;
+}
+export declare function useConfirmToast(): UseConfirmToastResult;

package/dist/package/browser/lib/useConfirmToast.js

@@ -0,0 +1,120 @@
+/**
+ * useConfirmToast — SSE subscription hook for tool.confirm-required events.
+ *
+ * Live stream only (D-6): subscribes to GET /api/events/stream?topic=tool.confirm-required.
+ * No SSE replay on reconnect — tokens that arrive before connection are ignored.
+ *
+ * Exposes:
+ *   - pendingConfirms: read-only array of pending confirm requests
+ *   - ack(token, decision): POST /api/tools/confirm { token, decision: 'allow' }
+ *   - deny(token): POST /api/tools/confirm { token, decision: 'deny' }
+ */
+import { useState, useEffect, useCallback } from 'react';
+import { parseSse } from './sse';
+/**
+ * Parse a raw SSE data string as a tool.confirm-required envelope.
+ * Returns the inner ConfirmPayload, or null if the envelope does not match.
+ */
+export function parseConfirmEnvelope(raw) {
+    let envelope;
+    try {
+        envelope = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof envelope !== 'object' ||
+        envelope === null ||
+        envelope.topic !== 'tool.confirm-required') {
+        return null;
+    }
+    const payload = envelope.payload;
+    if (typeof payload !== 'object' ||
+        payload === null ||
+        typeof payload.toolId !== 'string' ||
+        typeof payload.token !== 'string' ||
+        typeof payload.caller !== 'object' ||
+        payload.caller === null) {
+        return null;
+    }
+    const p = payload;
+    return {
+        toolId: p.toolId,
+        token: p.token,
+        caller: p.caller,
+        reason: typeof p.reason === 'string' ? p.reason : undefined,
+        message: typeof p.message === 'string' ? p.message : undefined,
+    };
+}
+const STREAM_URL = '/api/events/stream?topic=tool.confirm-required';
+const ACK_URL = '/api/tools/confirm';
+export function useConfirmToast() {
+    const [pendingConfirms, setPendingConfirms] = useState([]);
+    useEffect(() => {
+        let aborted = false;
+        const controller = new AbortController();
+        const run = async () => {
+            let res;
+            try {
+                res = await fetch(STREAM_URL, { signal: controller.signal });
+            }
+            catch {
+                return;
+            }
+            if (!res.ok || !res.body)
+                return;
+            try {
+                for await (const frame of parseSse(res.body)) {
+                    if (aborted)
+                        break;
+                    if (!frame.data)
+                        continue;
+                    const payload = parseConfirmEnvelope(frame.data);
+                    if (!payload)
+                        continue;
+                    setPendingConfirms((prev) => {
+                        if (prev.some((p) => p.token === payload.token))
+                            return prev;
+                        return [...prev, { ...payload, receivedAt: Date.now() }];
+                    });
+                }
+            }
+            catch {
+                // Stream ended or aborted — no-op.
+            }
+        };
+        void run();
+        return () => {
+            aborted = true;
+            controller.abort();
+        };
+    }, []);
+    const dismiss = useCallback((token) => {
+        setPendingConfirms((prev) => prev.filter((p) => p.token !== token));
+    }, []);
+    const ack = useCallback(async (token) => {
+        try {
+            await fetch(ACK_URL, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ token, decision: 'allow' }),
+            });
+        }
+        finally {
+            dismiss(token);
+        }
+    }, [dismiss]);
+    const deny = useCallback(async (token) => {
+        try {
+            await fetch(ACK_URL, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ token, decision: 'deny' }),
+            });
+        }
+        finally {
+            dismiss(token);
+        }
+    }, [dismiss]);
+    return { pendingConfirms, ack, deny };
+}

package/dist/package/browser/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/package/browser/lib/utils.js

@@ -0,0 +1,5 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/package/browser/lib/vag-action-bridge.d.ts

@@ -0,0 +1,2 @@
+/** bootUiBridge 调用一次(幂等):挂 window message 监听,可信 origin 才处理。 */
+export declare function installVagActionBridge(): void;

package/dist/package/browser/lib/vag-action-bridge.js

@@ -0,0 +1,130 @@
+/** vag-action-bridge —— editor 等 iframe 内 action 的 host 侧接入(P1-12)。
+ *
+ *  协议（只传可序列化数据，handler 留 iframe 本地，
+ *  interface 刻意不 import editor,inline 校验照 healthBridge 先例):
+ *
+ *    iframe → host  VAG_ACTION_MANIFEST { type, actions: [{ id, title, description?,
+ *                     inputSchema?, capability, surface?, timeoutMs? }] }
+ *                   (整表替换语义:同一 iframe 重发即覆盖它之前登记的全部 action)
+ *    host → iframe  VAG_ACTION_INVOKE { type, reqId, id, args }
+ *    iframe → host  VAG_ACTION_RESULT { type, reqId, result }(result = UiActionResult 形)
+ *
+ *  host 侧把 iframe action 注册成 **proxy action**(run = postMessage 往返),从而
+ *  ui_snapshot/ui_invoke/命令面板/右键 derive 全部自动覆盖 iframe 内功能——机制归
+ *  本文件,内容归各 iframe。注:editor 子模块侧的发消息端待 editor 仓落地(本文件
+ *  是 host 半边,协议以此为准)。
+ */
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { registerAction } from './action-registry';
+import { isTrustedMessageOrigin } from './trustedOrigins';
+const VALID_CAPS = new Set([
+    'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',
+]);
+const INVOKE_TIMEOUT_MS = 8_000;
+const MAX_ACTIONS_PER_FRAME = 200;
+/** 每个 iframe(按 source window)一份登记状态;重发 manifest = 整表替换。 */
+const frames = new Map();
+/** reqId → resolve(iframe 回 VAG_ACTION_RESULT 时解开)。 */
+const pendingInvokes = new Map();
+function sanitizeDecl(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    const id = typeof o.id === 'string' ? o.id.trim() : '';
+    const title = typeof o.title === 'string' ? o.title.trim() : '';
+    const capability = typeof o.capability === 'string' && VALID_CAPS.has(o.capability) ? o.capability : null;
+    // capability 是权限声明,非法值整条丢弃(与 server 侧 manifest 消毒同口径,fail-closed)。
+    if (!id || !title || !capability)
+        return null;
+    return {
+        id, title, capability,
+        ...(typeof o.description === 'string' ? { description: o.description } : {}),
+        ...(o.inputSchema && typeof o.inputSchema === 'object' ? { inputSchema: o.inputSchema } : {}),
+        ...(o.surface === 'ui' || o.surface === 'server' || o.surface === 'both' ? { surface: o.surface } : {}),
+        ...(typeof o.timeoutMs === 'number' && o.timeoutMs > 0 ? { timeoutMs: Math.floor(o.timeoutMs) } : {}),
+    };
+}
+function invokeInFrame(frame, id, args, timeoutMs) {
+    const reqId = `vag-${Math.random().toString(36).slice(2)}`;
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            pendingInvokes.delete(reqId);
+            resolve({ status: 'rejected', reason: `iframe did not answer within ${timeoutMs}ms` });
+        }, timeoutMs);
+        pendingInvokes.set(reqId, (result) => {
+            clearTimeout(timer);
+            pendingInvokes.delete(reqId);
+            resolve(result);
+        });
+        try {
+            frame.source.postMessage({ type: 'VAG_ACTION_INVOKE', reqId, id, args }, frame.origin);
+        }
+        catch (e) {
+            clearTimeout(timer);
+            pendingInvokes.delete(reqId);
+            resolve({ status: 'rejected', reason: `postMessage failed: ${e instanceof Error ? e.message : String(e)}` });
+        }
+    });
+}
+function handleManifest(source, origin, rawActions) {
+    // 整表替换:先注销该 iframe 之前登记的全部 proxy action(幂等,HMR/重载安全)。
+    const prev = frames.get(source);
+    if (prev)
+        for (const un of prev.unregister)
+            un();
+    const state = { source, origin, unregister: [] };
+    frames.set(source, state);
+    if (!Array.isArray(rawActions))
+        return;
+    for (const raw of rawActions.slice(0, MAX_ACTIONS_PER_FRAME)) {
+        const decl = sanitizeDecl(raw);
+        if (!decl)
+            continue;
+        const timeoutMs = Math.min(30_000, decl.timeoutMs ?? INVOKE_TIMEOUT_MS);
+        state.unregister.push(registerAction({
+            id: decl.id,
+            title: decl.title,
+            description: decl.description ?? `Invoke "${decl.title}" inside its panel (declared via VAG_ACTION_MANIFEST).`,
+            schema: decl.inputSchema ?? { type: 'object', properties: {} },
+            capability: decl.capability,
+            surface: decl.surface ?? 'ui',
+            timeoutMs,
+            available: () => {
+                try {
+                    return state.source.closed === false || state.source.closed === undefined
+                        ? true
+                        : 'origin iframe is gone (panel closed)';
+                }
+                catch {
+                    return 'origin iframe is gone (panel closed)';
+                }
+            },
+            run: (args) => invokeInFrame(state, decl.id, args, timeoutMs),
+        }));
+    }
+}
+let installed = false;
+/** bootUiBridge 调用一次(幂等):挂 window message 监听,可信 origin 才处理。 */
+export function installVagActionBridge() {
+    if (installed || typeof window === 'undefined')
+        return;
+    installed = true;
+    const onMessage = (e) => {
+        if (!isTrustedMessageOrigin(e.origin) || !e.data || typeof e.data !== 'object')
+            return;
+        const data = e.data;
+        if (data.type === 'VAG_ACTION_MANIFEST' && e.source && typeof e.source.postMessage === 'function') {
+            handleManifest(e.source, e.origin, data.actions);
+        }
+        else if (data.type === 'VAG_ACTION_RESULT' && typeof data.reqId === 'string') {
+            const resolve = pendingInvokes.get(data.reqId);
+            if (!resolve)
+                return;
+            const r = data.result;
+            resolve(r && (r.status === 'completed' || r.status === 'accepted' || r.status === 'rejected')
+                ? r
+                : { status: 'completed', ...(data.result !== undefined ? { stateDigest: data.result } : {}) });
+        }
+    };
+    void installWindowMessageObservation({ target: window, onMessage });
+}

package/dist/package/browser/main.d.ts

@@ -0,0 +1 @@
+import './styles/global.css';

package/dist/package/browser/main.js

@@ -0,0 +1,157 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './styles/global.css';
+// Relative import (not the '@forgeax/design' workspace alias): design lives
+// INSIDE this package (packages/design), and a workspace member depending on
+// its own nested member trips bun 1.3.14's --frozen-lockfile graph check
+// (install/frozen disagree → CI frozen gate永远红). Same precedent as
+// tailwind.config.ts. Root-workspace consumers (studio) keep the alias.
+import { applyTheme } from '../packages/design/theme';
+import { initI18n } from './i18n';
+import { App } from './App';
+// Dark-only today; dual-marks data-theme + .dark so tokens.css selectors and
+// Tailwind's `dark:` variant stay in lockstep. A light skin later only adds
+// token overrides — no .tsx change. index.html already sets these for no-flash;
+// this keeps it correct if the attribute is ever cleared.
+applyTheme('dark');
+// Restore the persisted UI language before first paint. English is the default
+// (source of truth); other languages are a user-facing overlay.
+initI18n();
+import { initAegis } from './lib/aegis';
+import { BrandProvider } from './brand';
+import { ErrorBoundary } from './components/ErrorBoundary';
+import { bootStageEntry } from './boot/driver';
+import { bootBroadcast } from './boot/broadcast';
+import { isTrustedMessageOrigin } from './lib/trustedOrigins';
+import { subscribeNarrativeCopilot } from './lib/narrative-copilot';
+import { subscribeFileActivityStream } from './lib/file-activity-stream';
+import { subscribePerceptionStream } from './lib/perception-stream';
+import { bootUiBridge } from './lib/ui-bridge';
+import { syncBrowserPrefsFromServer, startBrowserPrefsSync } from './lib/browser-prefs-sync';
+import { setCurrentProject } from './lib/project-context';
+import { getStudioProjectClient, hasStudioDomainClients, useShellStore } from './store';
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { decodeSurfaceFromLocation } from '@forgeax/app-shell/window';
+import { getSurfaceWindowingController, getWindowManager, isTauri } from './lib/platform';
+import { DetachedSurface } from './components/DetachedSurface';
+import { installHealthBridge } from './components/StatusBar/healthBridge';
+import { beginAppBoot, appBootSpan, endAppBoot } from './lib/trace';
+import { hasSessionClient } from './store-parts/session-client';
+// Boot Aegis (Galileo) front-end monitoring first, before any heavy boot work,
+// so early throws are captured. Inert unless VITE_AEGIS_* is configured (PROD,
+// or dev with VITE_AEGIS_DEV=1). MUST sit after all imports — Vite dev keeps
+// source statement order, so a call placed above its import never binds.
+initAegis();
+const rootEl = document.getElementById('root');
+if (!rootEl)
+    throw new Error('#root missing');
+// Desktop (WKWebView) renders the ambient scene-fx layer far more expensively
+// than Chrome: animated large-radius blur + a rotating conic-gradient keep the
+// compositor busy even when the UI is idle (a primary source of desktop jank /
+// fans spinning). Mark the document so scene-fx.css drops the infinite
+// animations and lightens the blur on desktop; the web form keeps the full look.
+if (isTauri())
+    document.documentElement.dataset.perf = 'lite';
+// fps / cow-survivor first-person mode pointer-lock bridge for Tauri.
+// WKWebView denies the web Pointer Lock API for embedded iframe content, so
+// games postMessage `{type:'fx-pointer-capture', capture:bool}` to the parent;
+// here we forward that to the Tauri command `set_pointer_capture` which calls
+// window.set_cursor_grab + set_cursor_visible(false) at the OS level. On web
+// this branch is a no-op (games still use realRequestLock.call(canvas) +
+// pointer-lock allow on the iframe). Wire ONCE at boot — listener stays for
+// the lifetime of the window.
+if (isTauri()) {
+    void (async () => {
+        try {
+            const { invoke } = await import('@tauri-apps/api/core');
+            const onMessage = (ev) => {
+                if (!isTrustedMessageOrigin(ev.origin))
+                    return; // foreign-origin guard
+                const data = ev.data;
+                if (data?.type !== 'fx-pointer-capture')
+                    return;
+                void invoke('set_pointer_capture', { capture: !!data.capture });
+            };
+            void installWindowMessageObservation({ target: window, onMessage });
+        }
+        catch (err) {
+            console.warn('[interface] fx-pointer-capture bridge unavailable:', err?.message ?? err);
+        }
+    })();
+}
+// Detached-window entry: when launched with `?surface=...` (a popped-out OS
+// window in the Tauri shell), render ONLY that surface — not the full IDE
+// shell. Same bundle, single index.html, no multi-entry build. The boot splash
+// in index.html is dismissed immediately since there's no heavy shell to wait
+// for. Business state stays consistent via the shared backend (/api · /ws).
+const detachedSurface = decodeSurfaceFromLocation();
+if (detachedSurface) {
+    // Boot splash is keyed off window.__forgeaxBoot; tell it we're done so the
+    // splash fades out for the lightweight detached view.
+    window.__forgeaxBoot?.done?.();
+    // Detached windows still need the store + live streams. Each OS window stays
+    // consistent through the shared backend. We deliberately skip the
+    // window-close→redock listener here (that's the main window's job).
+    bootStore();
+    createRoot(rootEl).render(_jsx(StrictMode, { children: _jsx(ErrorBoundary, { scope: "detached-surface", children: _jsx(BrandProvider, { children: _jsx(DetachedSurface, { surface: detachedSurface }) }) }) }));
+}
+else {
+    // Restore UI prefs, resolve the active game/project id, then mount the shell
+    // so DockRegion reads project-scoped layout keys on first paint.
+    void (async () => {
+        await syncBrowserPrefsFromServer();
+        initI18n();
+        try {
+            if (hasStudioDomainClients()) {
+                const j = await getStudioProjectClient().listProjects();
+                setCurrentProject(j.activeSlug ?? j.games?.[0]?.slug ?? 'default');
+            }
+        }
+        catch { /* non-critical — GameDirectoryModalHost retries */ }
+        startBrowserPrefsSync();
+        bootStageEntry();
+        bootFullShell(rootEl);
+    })();
+}
+// Shared store/stream bootstrap. NOTE (R4): chat's session-stream lives in
+// `@forgeax/chat` now and is wired by the Studio product assembly. The standalone
+// interface AppKit boot is chat-agnostic — it does not subscribe the chat
+// message stream (the interface foundation must not import the chat application).
+function bootStore() {
+    // Health/INFO bridge — capture shell errors + iframe-forwarded health signals
+    // (Play/Edit/plugin) into the status bar. Must run before any iframe mounts so
+    // early createApp failures are caught. Idempotent.
+    installHealthBridge();
+    bootBroadcast(); // R5/P1 唯一公共广播 socket（telemetry）
+    if (hasSessionClient()) {
+        subscribeNarrativeCopilot();
+        subscribeFileActivityStream();
+        subscribePerceptionStream();
+        void useShellStore.getState().initSessions();
+    }
+    bootUiBridge(); // UI 语义操作层(ActionRegistry + lease + ui_* 应答;方案:产品AI化-语义操作层)
+}
+function bootFullShell(el) {
+    // 全链路 trace:app.boot 初始化 trace(store-wiring + shell-mount;纯浏览器)。
+    beginAppBoot();
+    // R3 (2026-05-20 重做) —— boot 流程见 bootStore():subscribeSessionStream 先挂
+    // handler,再 initSessions → connectForgeaXWs。store 是唯一真值源。
+    appBootSpan('app.boot.store', () => bootStore());
+    // Windowing: when a detached surface window is closed by the user, redock it
+    // (the main window re-mounts its keep-alive iframe or retained Page anchor).
+    // Browser popup polling and Tauri destroyed events both converge here.
+    getWindowManager().onSurfaceWindowClosed((d) => {
+        getSurfaceWindowingController().markSurfaceDocked(d);
+    });
+    if (import.meta.env.DEV) {
+        // DevTools bridge — exposes the Zustand store to window.__dev so that the
+        // external forgeax-devtools panel (~/Dev/forgeax-devtools/) can read and
+        // patch store state without being part of this repo. Stripped in production.
+        window['__dev'] = useShellStore;
+    }
+    appBootSpan('app.boot.shell', () => {
+        createRoot(el).render(_jsx(StrictMode, { children: _jsx(ErrorBoundary, { scope: "studio-shell", children: _jsx(BrandProvider, { children: _jsx(App, {}) }) }) }));
+    });
+    endAppBoot();
+}

package/dist/package/browser/store-parts/domain-clients.d.ts

@@ -0,0 +1,149 @@
+/** Domain-shaped Studio service contracts injected by the product composition root. */
+export interface AgentCatalogEntry {
+    id: string;
+    role?: string;
+    avatarRules?: unknown;
+    [key: string]: unknown;
+}
+export interface AgentCatalogResponse {
+    agents: AgentCatalogEntry[];
+    agents_from_bus?: Array<{
+        id: string;
+        role: string;
+    }>;
+    activeSlug?: string | null;
+}
+export interface EngineRootCandidate {
+    path: string;
+    valid: boolean;
+    recommended?: boolean;
+}
+export interface ProjectRow {
+    slug: string;
+    name?: string;
+    brief?: string;
+    [key: string]: unknown;
+}
+export interface AndroidConfig {
+    applicationId: string;
+    name: string;
+    icon?: string;
+    orientation?: 'portrait' | 'landscape';
+}
+export type BuildProjectOptions = Record<string, unknown>;
+export interface BuildJobStatus {
+    jobId: string;
+    status: 'pending' | 'running' | 'success' | 'failed' | 'error' | 'cancelled';
+    [key: string]: unknown;
+}
+export interface BuildHistoryRecord {
+    id: string;
+    slug: string;
+    platform: string;
+    [key: string]: unknown;
+}
+export interface ActiveProjectSelection {
+    activeSlug: string | null;
+    runtime?: RuntimeScopeState;
+}
+export type RuntimeScopeStatus = 'unbound' | 'transitioning' | 'ready' | 'degraded' | 'unavailable';
+export interface RuntimeAssetDiagnostic {
+    code: string;
+    severity: 'info' | 'warning' | 'blocking';
+    message?: string;
+    hint?: string;
+}
+export interface RuntimeCatalogRoot {
+    readonly root: string;
+    readonly catalogPrefix: string;
+}
+export interface RuntimeAssetBinding {
+    schemaVersion: 'runtime-asset-binding-v1';
+    gameId: string;
+    scopeId: string;
+    generation: number;
+    status: RuntimeScopeStatus;
+    catalogUrl: string;
+    importUrlBase: string;
+    packageUrlBase: string;
+    catalogRoots?: readonly RuntimeCatalogRoot[];
+    authority?: 'authoritative' | 'degraded';
+    diagnostics?: readonly RuntimeAssetDiagnostic[];
+}
+export interface RuntimeScopeState {
+    status: RuntimeScopeStatus;
+    binding?: RuntimeAssetBinding;
+    error?: string;
+}
+export interface CleanBuildResult {
+    totalBytes: number;
+    targets: Array<{
+        path: string;
+        existed: boolean;
+        removed: boolean;
+        bytes: number;
+        error?: string;
+    }>;
+}
+export interface AgentCatalogClient {
+    listAgents(opts?: {
+        lang?: 'zh' | 'en';
+    }): Promise<AgentCatalogResponse>;
+}
+export interface StudioProjectClient {
+    getActiveProject(): Promise<ActiveProjectSelection>;
+    setActiveProject(slug: string): Promise<ActiveProjectSelection>;
+    subscribeActiveProject(listener: (selection: ActiveProjectSelection) => void): () => void;
+    listProjects(): Promise<{
+        games: ProjectRow[];
+        activeSlug: string | null;
+    }>;
+    createProject(input: {
+        slug: string;
+        name: string;
+        brief: string;
+        template?: string;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+        slug?: string;
+        session?: {
+            sid: string;
+        };
+    }>;
+    linkProject(path: string): Promise<{
+        ok: boolean;
+        error?: string;
+        slug?: string;
+    }>;
+    deleteProject(slug: string): Promise<void>;
+}
+export interface StudioBuildClient {
+    buildProject(slug: string, options?: BuildProjectOptions): Promise<{
+        jobId?: string;
+        async?: boolean;
+        ok?: boolean;
+        [key: string]: unknown;
+    }>;
+    pollBuildJob(jobId: string): Promise<BuildJobStatus>;
+    getEngineRoots(): Promise<{
+        roots: EngineRootCandidate[];
+    }>;
+    cleanBuilds(): Promise<CleanBuildResult>;
+    listBuildHistory(): Promise<{
+        records: BuildHistoryRecord[];
+    }>;
+    deleteBuildHistory(id: string, opts?: {
+        clean?: boolean;
+    }): Promise<void>;
+}
+export interface StudioDomainClients {
+    agents: AgentCatalogClient;
+    projects: StudioProjectClient;
+    builds: StudioBuildClient;
+}
+export declare function configureStudioDomainClients(clients: StudioDomainClients): void;
+export declare function hasStudioDomainClients(): boolean;
+export declare const getAgentCatalogClient: () => AgentCatalogClient;
+export declare const getStudioProjectClient: () => StudioProjectClient;
+export declare const getStudioBuildClient: () => StudioBuildClient;

package/dist/package/browser/store-parts/domain-clients.js

@@ -0,0 +1,17 @@
+/** Domain-shaped Studio service contracts injected by the product composition root. */
+let configuredClients = null;
+export function configureStudioDomainClients(clients) {
+    configuredClients = clients;
+}
+export function hasStudioDomainClients() {
+    return configuredClients !== null;
+}
+function requireClients() {
+    if (!configuredClients) {
+        throw new Error('No Studio domain clients configured. The Studio composition root must inject them before booting interface.');
+    }
+    return configuredClients;
+}
+export const getAgentCatalogClient = () => requireClients().agents;
+export const getStudioProjectClient = () => requireClients().projects;
+export const getStudioBuildClient = () => requireClients().builds;

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

@@ -0,0 +1,4 @@
+import type { AppState } from '../store';
+type SetAppState = (partial: Partial<AppState> | ((state: AppState) => Partial<AppState>)) => void;
+export declare function createObservabilityState(set: SetAppState): Pick<AppState, 'consoleLog' | 'pushConsole' | 'clearConsole' | 'networkLog' | 'pushNetwork' | 'clearNetwork' | 'telemetry' | 'pushTelemetry' | 'clearTelemetry'>;
+export {};

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

@@ -0,0 +1,35 @@
+import { recordLog } from '../lib/logSink';
+export function createObservabilityState(set) {
+    return {
+        consoleLog: [],
+        pushConsole: (entry) => {
+            recordLog('console', entry);
+            set((s) => ({
+                consoleLog: s.consoleLog.length >= 500
+                    ? [...s.consoleLog.slice(s.consoleLog.length - 499), entry]
+                    : [...s.consoleLog, entry],
+            }));
+        },
+        clearConsole: () => set({ consoleLog: [] }),
+        networkLog: [],
+        pushNetwork: (entry) => {
+            recordLog('network', entry);
+            set((s) => ({
+                networkLog: s.networkLog.length >= 500
+                    ? [...s.networkLog.slice(s.networkLog.length - 499), entry]
+                    : [...s.networkLog, entry],
+            }));
+        },
+        clearNetwork: () => set({ networkLog: [] }),
+        telemetry: [],
+        pushTelemetry: (records) => {
+            if (!records.length)
+                return;
+            set((s) => {
+                const next = [...s.telemetry, ...records];
+                return { telemetry: next.length > 500 ? next.slice(next.length - 500) : next };
+            });
+        },
+        clearTelemetry: () => set({ telemetry: [] }),
+    };
+}