@forgeax/interface 0.4.1

package/dist/package/node/lib/deep-link-bus.js

@@ -0,0 +1,35 @@
+// 跨-surface 深链意图 —— 建在 interface bus primitive 之上的一层薄封装（R5/P2）。
+//
+// 背景：原来这些"点了 A 面里的东西 → 跳到 B 面并高亮/展开/过滤"的意图，是往 interface
+// store 里塞 `pending*` 字段（producer set、consumer 读到后 act + 清空）实现的。
+// 那让 interface store 变成了跨 app 导航总线（app 领域态漏进 foundation）。R5/P2 把它们改成走 bus：
+//   - producer：`emitDeepLink(topic, payload)`  —— retain 一次（快照语义）
+//   - consumer：`useDeepLink(topic)` → [value, clear]，clear 时清 retained + 本地
+//
+// 为什么 retain：这些深链常跨一次 mode 切换（如 Sidebar 点一下 → setMode('bus') →
+// BusAdminPanel 此刻才挂载）。retain 让"晚挂载的消费者"在 subscribe 时立即补到值，
+// 复刻原 store 字段"持续到被消费"的行为。消费者消费后 clear，避免重复触发。
+//
+// interface foundation 纯度说明：topic 字符串是"跨 surface 导航意图"，其消费者（BusAdminPanel/Sidebar
+// 等壳内 surface）目前仍驻留 interface（见 17b §7.4 —— 这些是壳/残留，非新耦合）。
+// bus primitive 本身零 app 语义；本文件只是把散落的 topic 常量收敛到一处、加类型。
+import { useEffect, useState, useCallback } from 'react';
+import { publish, subscribe, peek, clearRetained } from './bus.js';
+/** producer：发一条深链意图（retain 一次，晚挂载的消费者会补到）。 */
+export function emitDeepLink(topic, payload) {
+    publish(topic, payload, { retain: true });
+}
+/** producer：清掉某 topic 的 retained 快照 + 通知在线消费者复位（原 `setPendingX(null)`）。
+ *  用于"打开 B 面但不要带上一次残留的深链"（如 Dashboard goBus 只想开面板、不预过滤）。 */
+export function clearDeepLink(topic) {
+    clearRetained(topic);
+    publish(topic, null);
+}
+/** consumer hook：镜像原 `pendingX / setPendingX(null)` 对，但值由 interface bus 承载。
+ *  返回 `[value, clear]`：value 来自 retained 快照 + 后续 publish；clear() 清 retained + 本地。 */
+export function useDeepLink(topic) {
+    const [val, setVal] = useState(() => peek(topic) ?? null);
+    useEffect(() => subscribe(topic, (p) => setVal(p ?? null)), [topic]);
+    const clear = useCallback(() => { clearRetained(topic); setVal(null); }, [topic]);
+    return [val, clear];
+}

package/dist/package/node/lib/dialog.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Imperative async replacement for the browser's blocking `confirm()` /
+ * `alert()`, rendered with the shadcn AlertDialog so it matches the design
+ * system and is non-blocking.
+ *
+ *   if (!(await confirmDialog({ body: '确认删除?', danger: true }))) return;
+ *   await alertDialog({ body: '保存失败' });
+ *   const decision = await unsavedChangesDialog({ body: '…' });
+ *
+ * A single <DialogHost /> (mounted in App) subscribes to a module-level queue.
+ * This is plain UI plumbing — it carries no tool/surface semantics, so it does
+ * not touch the dual-modality path.
+ */
+import { useEffect, useState } from 'react';
+import { useTranslation } from '../i18n/index.js';
+import { AlertDialog, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel, } from '../components/ui/alert-dialog.js';
+let queue = [];
+let seq = 0;
+const listeners = new Set();
+function emit() {
+    const snapshot = queue.slice();
+    listeners.forEach((l) => l(snapshot));
+}
+function takeRequest(id) {
+    const req = queue.find((r) => r.id === id);
+    if (!req)
+        return undefined;
+    queue = queue.filter((r) => r.id !== id);
+    emit();
+    return req;
+}
+function resolveConfirmAlert(id, value) {
+    const req = takeRequest(id);
+    if (!req || req.kind === 'unsaved')
+        return;
+    req.resolve(value);
+}
+function resolveUnsaved(id, value) {
+    const req = takeRequest(id);
+    if (!req || req.kind !== 'unsaved')
+        return;
+    req.resolve(value);
+}
+export function confirmDialog(options) {
+    return new Promise((resolve) => {
+        queue.push({ id: ++seq, kind: 'confirm', options, resolve });
+        emit();
+    });
+}
+export function alertDialog(options = {}) {
+    return new Promise((resolve) => {
+        queue.push({ id: ++seq, kind: 'alert', options, resolve: () => resolve() });
+        emit();
+    });
+}
+export function __resetDialogQueueForTests() {
+    queue = [];
+    emit();
+}
+export function unsavedChangesDialog(options = {}) {
+    return new Promise((resolve) => {
+        queue.push({ id: ++seq, kind: 'unsaved', options, resolve });
+        emit();
+    });
+}
+export function DialogHost() {
+    const { t } = useTranslation();
+    const [reqs, setReqs] = useState(queue);
+    useEffect(() => {
+        const listener = (next) => setReqs(next);
+        listeners.add(listener);
+        listener(queue.slice());
+        return () => {
+            listeners.delete(listener);
+        };
+    }, []);
+    const head = reqs[0];
+    if (!head)
+        return null;
+    const isConfirm = head.kind === 'confirm';
+    const isUnsaved = head.kind === 'unsaved';
+    return (_jsx(AlertDialog, { open: true, onOpenChange: (open) => {
+            if (!open) {
+                if (isUnsaved)
+                    resolveUnsaved(head.id, 'cancel');
+                else
+                    resolveConfirmAlert(head.id, false);
+            }
+        }, children: _jsxs(AlertDialogContent, { children: [_jsxs(AlertDialogHeader, { children: [head.options.title ? (_jsx(AlertDialogTitle, { children: head.options.title })) : (_jsx(AlertDialogTitle, { className: "sr-only", children: isUnsaved
+                                ? t('dialog.unsavedTitle')
+                                : isConfirm
+                                    ? t('dialog.confirmActionTitle')
+                                    : t('dialog.alertTitle') })), head.options.body && (
+                        // Body is the primary message here (most confirm/alert calls pass
+                        // no title), so use full foreground instead of the muted default —
+                        // muted-foreground (60% opacity) reads as illegible grey-on-dark.
+                        _jsx(AlertDialogDescription, { asChild: true, className: "whitespace-pre-line text-foreground", children: _jsx("div", { children: head.options.body }) }))] }), _jsx(AlertDialogFooter, { children: isUnsaved ? (_jsxs(_Fragment, { children: [_jsx(AlertDialogCancel, { onClick: () => resolveUnsaved(head.id, 'cancel'), children: head.options.cancelText ?? t('common.cancel') }), _jsx(AlertDialogAction, { className: "bg-destructive text-destructive-foreground hover:bg-destructive/90", onClick: () => resolveUnsaved(head.id, 'discard'), children: head.options.discardText ?? t('dialog.discardChanges') }), _jsx(AlertDialogAction, { autoFocus: true, onClick: () => resolveUnsaved(head.id, 'save'), children: head.options.saveText ?? t('common.save') })] })) : (_jsxs(_Fragment, { children: [isConfirm && (_jsx(AlertDialogCancel, { onClick: () => resolveConfirmAlert(head.id, false), children: head.options.cancelText ?? t('common.cancel') })), _jsx(AlertDialogAction, { autoFocus: true, className: isConfirm && head.options.danger
+                                    ? 'bg-destructive text-destructive-foreground hover:bg-destructive/90'
+                                    : undefined, onClick: () => resolveConfirmAlert(head.id, true), children: isConfirm
+                                    ? head.options.confirmText ?? t('common.confirm')
+                                    : head.options.okText ?? t('common.ok') })] })) })] }) }));
+}

package/dist/package/node/lib/editor-facts-bus.js

@@ -0,0 +1,25 @@
+// editor-facts bus contract — the read-side view models + topic names for the
+// footer's Events / Diagnostics panels.
+//
+// Data-plane wiring (ADR-0030 §4): the footer panels live in interface but the
+// truth (editor gateway operation runs + engine/scene/asset facts) lives in the
+// studio/editor realm, which interface must never import. So studio (the owner
+// of the editor realm) publishes onto the shared cross-app bus with `retain`,
+// and these interface panels subscribe. interface only knows these flat view
+// models — nothing about the editor transport, gateway, or `@forgeax/editor`.
+//
+// The topic strings are exported so the studio publisher imports the SAME names
+// (single source of truth). interface's own `BusTopics` stays empty per the bus
+// design; the studio publisher does the `declare module` augmentation next to
+// its `publish()` calls.
+import { useBusSnapshot } from './use-bus-snapshot.js';
+export const EDITOR_RUNS_TOPIC = 'editor:gatewayRuns';
+export const EDITOR_FACTS_TOPIC = 'editor:facts';
+/** Subscribe to the latest gateway-run feed (empty until studio publishes). */
+export function useGatewayRuns() {
+    return useBusSnapshot(EDITOR_RUNS_TOPIC) ?? [];
+}
+/** Subscribe to the latest editor facts (undefined until studio publishes). */
+export function useEditorFacts() {
+    return useBusSnapshot(EDITOR_FACTS_TOPIC);
+}

package/dist/package/node/lib/extension-api.js

@@ -0,0 +1,90 @@
+export async function listSharedCapabilities() {
+    const empty = {
+        generation: 0,
+        loadedAt: 0,
+        capabilities: [],
+        issues: [],
+    };
+    const res = await fetch('/api/extensions/capabilities');
+    if (!res.ok || !res.headers.get('content-type')?.includes('application/json'))
+        return empty;
+    return (await res.json());
+}
+export function pickLang(text, lang = 'zh', fallback = '') {
+    if (!text)
+        return fallback;
+    if (typeof text === 'string')
+        return text;
+    return text[lang] ?? text.zh ?? text.en ?? fallback;
+}
+/**
+ * Strip known package scopes from a manifest id → flat marketplace slug.
+ * Longer scopes first so `@forgeax-extension/…` is never misread as `@forgeax/…`.
+ */
+export function extensionIdSlug(id) {
+    return id
+        .replace(/^@forgeax-extension\//, '')
+        .replace(/^@forgeax\//, '');
+}
+/** Render the browser-safe source descriptor returned by the runtime. */
+export function extensionManifestSourceLabel(extension) {
+    if (!extension.source)
+        return `extension:${extension.id}@${extension.version}`;
+    if (extension.source.origin === 'npm') {
+        return `npm:${extension.id}@${extension.version}/forgeax-extension.json`;
+    }
+    return `${extension.source.origin}:${extension.source.relativeManifestPath}`;
+}
+export async function listExtensions(kind) {
+    const url = kind
+        ? `/api/extensions/list?kind=${encodeURIComponent(kind)}`
+        : '/api/extensions/list';
+    const empty = { kind: kind ?? null, count: 0, items: [] };
+    const res = await fetch(url);
+    // The extension bus is a Studio-only product surface. The
+    // standalone editor has NO bus router, so its absence is EXPECTED, not an
+    // error — degrade to an empty list either way the "no backend" shows up:
+    //   - no `--game`: unknown /api routes fall to the SPA fallback → 200 + html
+    //   - with `--game`: the game-backend answers non-bus routes → 404 + json
+    // (Before, only the html case degraded; the 404+json slipped past the !ok
+    // guard and threw an Uncaught error in DockShell's boot effect.)
+    if (!res.ok)
+        return empty;
+    if (!res.headers.get('content-type')?.includes('application/json')) {
+        return empty;
+    }
+    const payload = (await res.json());
+    if (!Array.isArray(payload.items))
+        return empty;
+    return {
+        kind: typeof payload.kind === 'string' || payload.kind === null ? payload.kind : empty.kind,
+        count: typeof payload.count === 'number' ? payload.count : payload.items.length,
+        ...(typeof payload.generation === 'number' ? { generation: payload.generation } : {}),
+        items: payload.items,
+    };
+}
+// Shared short-TTL cache + in-flight dedupe for the full (no-kind) plugin
+// list. Many surfaces (ExtensionHostPanel, activity entries, BuildBadge, …)
+// fetch this concurrently; without dedupe each mount fires its own request and
+// a single slow/failed one can leave that panel stuck. `force` bypasses the
+// TTL (used by pollers that need to observe a manifest that just gained
+// entry.standalone) but still rides any in-flight request.
+let _busAllCache = null;
+let _busAllInflight = null;
+const BUS_ALL_TTL_MS = 2000;
+export async function listExtensionsShared(opts) {
+    if (!opts?.force && _busAllCache && Date.now() - _busAllCache.ts < BUS_ALL_TTL_MS) {
+        return _busAllCache.data;
+    }
+    if (_busAllInflight)
+        return _busAllInflight;
+    _busAllInflight = listExtensions()
+        .then((data) => {
+        _busAllCache = { ts: Date.now(), data };
+        return data;
+    })
+        .finally(() => {
+        _busAllInflight = null;
+    });
+    return _busAllInflight;
+}

package/dist/package/node/lib/file-activity-stream.js

@@ -0,0 +1,123 @@
+/** file-activity-stream — interface side of the per-session file-activity
+ *  ledger.
+ *
+ *  Subscribes to `onSessionEvent` and consumes two event types emitted by
+ *  the server's AgentFsRecorder (packages/server/src/fs/agent-fs-recorder.ts):
+ *
+ *    file-activity:start  → an agent is about to write a file (lock on)
+ *    file-activity:done   → write completed; ledger has the new record
+ *
+ *  We expose two pieces of derived state:
+ *
+ *    - `useFileLocks(sid)` — Map<absPath, { agentPath, op, since }> of files
+ *      currently being edited. Drives the 🔒 indicator on AgentsPanel /
+ *      Page rows.
+ *    - `useFileActivityVersion(sid)` — monotonically increasing counter that
+ *      bumps every time a 'done' event arrives. Panels that fetch the
+ *      ledger via REST (`/api/sessions/:sid/file-activity`) include this
+ *      version in their useEffect deps to auto-refresh on writes — no
+ *      polling needed.
+ *
+ *  Events with type `file-activity:*` are routed here exclusively; the
+ *  session-stream dispatch explicitly skips them (they'd otherwise be
+ *  rendered as system messages by the fallback path). */
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { getSessionClient } from '../store-parts/session-client.js';
+const _state = new Map();
+const _listeners = new Set();
+function getOrInit(sid) {
+    let s = _state.get(sid);
+    if (!s) {
+        s = { locks: new Map(), version: 0 };
+        _state.set(sid, s);
+    }
+    return s;
+}
+function notify() {
+    for (const l of _listeners)
+        l();
+}
+function dispatchFileActivity(evt) {
+    const t = evt.event.type;
+    if (t !== 'file-activity:start' && t !== 'file-activity:done')
+        return;
+    const sid = evt.sid;
+    const p = evt.event.payload;
+    if (typeof p.path !== 'string' || typeof p.agentPath !== 'string')
+        return;
+    const state = getOrInit(sid);
+    if (t === 'file-activity:start') {
+        state.locks.set(p.path, {
+            agentPath: p.agentPath,
+            op: p.op ?? 'write',
+            since: p.ts ?? Date.now(),
+        });
+    }
+    else {
+        state.locks.delete(p.path);
+        state.version += 1;
+    }
+    notify();
+}
+/** Wired in main.tsx alongside subscribeSessionStream. Idempotent — same
+ *  handler key, HMR-safe. */
+export function subscribeFileActivityStream() {
+    getSessionClient().onSessionEvent('file-activity', dispatchFileActivity);
+}
+function subscribe(cb) {
+    _listeners.add(cb);
+    return () => { _listeners.delete(cb); };
+}
+/** React hook — locks for a given session. Re-renders whenever any
+ *  file-activity event for that sid arrives. Returns empty Map for unknown
+ *  / inactive sids. */
+export function useFileLocks(sid) {
+    const snapshot = useSyncExternalStore(subscribe, () => (sid ? _state.get(sid)?.locks ?? _emptyLocks : _emptyLocks), () => _emptyLocks);
+    return snapshot;
+}
+const _emptyLocks = new Map();
+/** React hook — bumps every time a file-activity:done lands for `sid`.
+ *  Plug into useEffect deps to revalidate ledger fetches without polling. */
+export function useFileActivityVersion(sid) {
+    const [v, setV] = useState(0);
+    useEffect(() => {
+        if (!sid)
+            return;
+        return subscribe(() => {
+            const next = _state.get(sid)?.version ?? 0;
+            setV(next);
+        });
+    }, [sid]);
+    return v;
+}
+/** Evict a session's accumulated lock/version state. The module-level `_state`
+ *  Map grows one entry per session that ever emits a file-activity event and was
+ *  NEVER pruned, so every closed session permanently retained its entry (mem leak
+ *  case-10 — symmetric to store.ts closeSession evicting liveAgents /
+ *  agentFileActivity). closeSession calls this so closed sessions don't linger. */
+export function dropFileActivitySession(sid) {
+    if (_state.delete(sid))
+        notify();
+}
+/** Test / debug helper — clears all in-memory state. */
+export function _resetFileActivityStreamForTesting() {
+    _state.clear();
+    notify();
+}
+/** Test / debug — number of sessions currently retained in `_state`. The
+ *  module-private Map is unreachable from the store DEV bridge, so the leak repro
+ *  reads it through this seam. */
+export function _fileActivityStreamSessionCount() {
+    return _state.size;
+}
+/** Test / debug — seed a session's `_state` entry with `locks` open file locks,
+ *  exactly the way a live `file-activity:start` event would (getOrInit + locks.set).
+ *  Lets the deterministic repro exercise the close-session leak without a live WS. */
+export function _seedFileActivityForTest(sid, locks) {
+    const st = getOrInit(sid);
+    for (let i = 0; i < locks; i++) {
+        st.locks.set('seed/' + sid + '/' + i + '.ts', { agentPath: 'agents/forge', op: 'edit', since: 0 });
+    }
+    st.version += 1;
+    notify();
+}

package/dist/package/node/lib/file-family.js

@@ -0,0 +1,25 @@
+/**
+ * Shared file-family taxonomy used by the interface file tree and chat assets.
+ *
+ * Keep this module free of React and CSS imports.  The family key is the
+ * contract; visual consumers map it to `--fx-family-*` tokens.
+ */
+export const FAMILY_ORDER = [
+    { key: 'code', label: 'CODE', extensions: ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs'] },
+    { key: 'config', label: 'CFG', extensions: ['json', 'json5', 'jsonc', 'lock', 'yaml', 'yml', 'toml', 'ini', 'env'] },
+    { key: 'doc', label: 'DOC', extensions: ['md', 'markdown', 'txt', 'rst', 'adoc'] },
+    { key: 'scene', label: 'SCENE', extensions: ['scene', 'fxscene'] },
+    { key: 'pack', label: 'PACK', extensions: ['pack', 'fxpack', 'zip', 'tar', 'gz'] },
+    { key: 'meta', label: 'META', extensions: ['meta'] },
+    { key: 'image', label: 'IMG', extensions: ['png', 'jpg', 'jpeg', 'webp', 'gif', 'svg', 'ico', 'avif'] },
+    { key: 'audio', label: 'AUD', extensions: ['mp3', 'wav', 'ogg', 'flac', 'm4a', 'aac'] },
+    { key: 'model', label: 'MODEL', extensions: ['glb', 'gltf', 'fbx', 'obj', 'dae', 'blend', '3ds'] },
+    { key: 'data', label: 'DATA', extensions: ['csv', 'tsv', 'xml', 'bin', 'dat', 'db', 'sqlite', 'sqlite3'] },
+];
+const EXTENSION_TO_FAMILY = new Map(FAMILY_ORDER.flatMap(({ key, extensions }) => extensions.map((extension) => [extension, key])));
+/** Classify a file path by its final extension. Unknown files are `data`. */
+export function familyOf(path) {
+    const name = path.replace(/\\/g, '/').split('/').pop() ?? path;
+    const extension = name.includes('.') ? name.split('.').pop()?.toLowerCase() ?? '' : '';
+    return EXTENSION_TO_FAMILY.get(extension) ?? 'data';
+}

package/dist/package/node/lib/game-templates.js

@@ -0,0 +1,15 @@
+function isGameTemplate(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.slug === 'string' && candidate.slug.length > 0
+        && typeof candidate.name === 'string' && candidate.name.length > 0);
+}
+/** Read the engine-owned template catalog used by both onboarding and New Game. */
+export async function listGameTemplates() {
+    const response = await fetch('/api/projects/templates');
+    if (!response.ok)
+        throw new Error(`listGameTemplates → HTTP ${response.status}`);
+    const body = (await response.json());
+    return Array.isArray(body.templates) ? body.templates.filter(isGameTemplate) : [];
+}