@forgeax/interface 0.4.1

package/dist/package/browser/lib/deep-link-bus.d.ts

@@ -0,0 +1,10 @@
+/** 已登记的跨-surface 深链 topic。payload 见下方 map。 */
+export type DeepLinkTopic = 'bus:expand-plugin' | 'bus:filter-kind' | 'sidebar:focus-plugin' | 'sidebar:flash-kind' | 'chat:flash-bus-chip';
+/** producer：发一条深链意图（retain 一次，晚挂载的消费者会补到）。 */
+export declare function emitDeepLink(topic: DeepLinkTopic, payload: string): void;
+/** producer：清掉某 topic 的 retained 快照 + 通知在线消费者复位（原 `setPendingX(null)`）。
+ *  用于"打开 B 面但不要带上一次残留的深链"（如 Dashboard goBus 只想开面板、不预过滤）。 */
+export declare function clearDeepLink(topic: DeepLinkTopic): void;
+/** consumer hook：镜像原 `pendingX / setPendingX(null)` 对，但值由 interface bus 承载。
+ *  返回 `[value, clear]`：value 来自 retained 快照 + 后续 publish；clear() 清 retained + 本地。 */
+export declare function useDeepLink(topic: DeepLinkTopic): [string | null, () => void];

package/dist/package/browser/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';
+/** 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/browser/lib/dialog.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { type ReactNode } from 'react';
+export interface ConfirmOptions {
+    title?: string;
+    body?: ReactNode;
+    confirmText?: string;
+    cancelText?: string;
+    /** Style the confirm button as destructive. */
+    danger?: boolean;
+}
+export interface AlertOptions {
+    title?: string;
+    body?: ReactNode;
+    okText?: string;
+}
+export type UnsavedChangesDecision = 'save' | 'discard' | 'cancel';
+export interface UnsavedChangesOptions {
+    title?: string;
+    body?: ReactNode;
+    saveText?: string;
+    discardText?: string;
+    cancelText?: string;
+}
+export declare function confirmDialog(options: ConfirmOptions): Promise<boolean>;
+export declare function alertDialog(options?: AlertOptions): Promise<void>;
+export declare function __resetDialogQueueForTests(): void;
+export declare function unsavedChangesDialog(options?: UnsavedChangesOptions): Promise<UnsavedChangesDecision>;
+export declare function DialogHost(): React.ReactElement | null;

package/dist/package/browser/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';
+import { AlertDialog, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel, } from '../components/ui/alert-dialog';
+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/browser/lib/editor-facts-bus.d.ts

@@ -0,0 +1,27 @@
+/** One editor gateway operation dispatch (the "事件" feed row). */
+export interface GatewayRun {
+    readonly runId: string;
+    /** e.g. "document.edit" / "asset.import". */
+    readonly operationId: string;
+    /** "succeeded" | "failed" | "running" | … (kept open — carrier owns the set). */
+    readonly status: string;
+    /** epoch ms; 0 when the carrier didn't stamp one. */
+    readonly ts: number;
+    readonly error?: string;
+}
+/** Live engine / project / scene / asset facts (the diagnostics popover). */
+export interface EditorFacts {
+    /** Runtime identity, e.g. "game-runtime/v1 · browser". */
+    readonly engine: string;
+    /** Active game slug. */
+    readonly project: string;
+    /** Current scene id/name. */
+    readonly scene: string;
+    readonly assets: number;
+}
+export declare const EDITOR_RUNS_TOPIC = "editor:gatewayRuns";
+export declare const EDITOR_FACTS_TOPIC = "editor:facts";
+/** Subscribe to the latest gateway-run feed (empty until studio publishes). */
+export declare function useGatewayRuns(): readonly GatewayRun[];
+/** Subscribe to the latest editor facts (undefined until studio publishes). */
+export declare function useEditorFacts(): EditorFacts | undefined;

package/dist/package/browser/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';
+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/browser/lib/extension-api.d.ts

@@ -0,0 +1,140 @@
+import type { ExtensionManifestV2 } from '@forgeax/types';
+export interface ExtensionModelBindingInfo {
+    channel: string;
+    vendor: string;
+    models: string[];
+    roles?: string[];
+}
+export interface ExtensionSkillInfo {
+    id: string;
+    trigger: string;
+}
+export interface ExtensionToolInfo {
+    id: string;
+    exposedToAI?: boolean;
+}
+export interface ExtensionEventInfo {
+    name: string;
+}
+export interface ExtensionCliProviderInfo {
+    id: string;
+    displayName: string;
+    models?: string[];
+    capabilities: {
+        streaming: boolean;
+        thinking: boolean;
+        toolCalls: boolean;
+        subAgents: boolean;
+        sessions: boolean;
+    };
+}
+export interface ExtensionEntryInfo {
+    frontend?: string;
+    /** Phase A3: standalone iframe-served plugin entry. When `start`/`port` is
+     *  set, the host can mount the plugin via an iframe + postMessage RPC
+     *  (createExtensionPort). Gated by `VITE_FX_USE_IFRAME=true` until B-phase. */
+    standalone?: {
+        start?: string;
+        port?: number;
+        readyProbe?: string;
+        embeddedAlso?: boolean;
+    };
+}
+export interface ExtensionAgentInfo {
+    id: string;
+    role?: string;
+    personaFile?: string;
+    memoryDir?: string;
+    preferredCliProvider?: string;
+    defaultLang?: string;
+    multiInstance?: boolean;
+}
+export interface ExtensionSourceInfo {
+    origin: 'builtin' | 'npm' | 'user' | 'project' | 'dev';
+    /** Browser-safe path relative to the selected origin root. */
+    relativeManifestPath: string;
+}
+export interface ExtensionInfo {
+    id: string;
+    version: string;
+    kind: string;
+    displayName: {
+        zh?: string;
+        en?: string;
+        ja?: string;
+    } | string;
+    description?: {
+        zh?: string;
+        en?: string;
+        ja?: string;
+    } | string;
+    icon?: string;
+    experimental?: boolean;
+    contributes?: ExtensionManifestV2['contributes'];
+    modelBinding?: ExtensionModelBindingInfo;
+    skills?: ExtensionSkillInfo[];
+    tools?: ExtensionToolInfo[];
+    events?: ExtensionEventInfo[];
+    cliProvider?: ExtensionCliProviderInfo;
+    agent?: ExtensionAgentInfo;
+    entry?: ExtensionEntryInfo;
+    /** Explicit host-validated runtime metadata for externally-owned development artifacts. */
+    frontendUrl?: string;
+    moduleUrl?: string;
+    allowedOrigin?: string;
+    runtimeMode?: 'native-module' | 'dev' | 'embedded' | 'standalone';
+    registryGeneration?: number;
+    /** Runtime-resolved origin; never an absolute host filesystem path. */
+    source?: ExtensionSourceInfo;
+    /** kind=agent 才有：统一命名。title=「中文职能·英文名」，sub=灰字英文职能。 */
+    naming?: {
+        title: string;
+        sub: string;
+    };
+}
+export interface ExtensionListResponse {
+    kind: string | null;
+    count: number;
+    generation?: number;
+    items: ExtensionInfo[];
+}
+export type SharedCapabilityKind = 'skill' | 'command' | 'mcp' | 'extension' | 'memory' | 'tool';
+export interface SharedCapabilityInfo {
+    capabilityId: string;
+    kind: SharedCapabilityKind;
+    extensionId: string;
+    extensionVersion: string;
+    origin: 'builtin' | 'user' | 'project';
+    trustTier: 'own' | 'imported';
+    localId: string;
+    generation: number;
+    lifecycle: {
+        state: 'load' | 'activate' | 'ready' | 'reload' | 'deactivate' | 'broken';
+        reloadable: boolean;
+        requiresRestart: boolean;
+    };
+    shadowedBy: Array<{
+        origin: string;
+        originPath: string;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+export interface SharedCapabilityListResponse {
+    generation: number;
+    loadedAt: number;
+    capabilities: SharedCapabilityInfo[];
+    issues: string[];
+}
+export declare function listSharedCapabilities(): Promise<SharedCapabilityListResponse>;
+export declare function pickLang(text: ExtensionInfo['displayName'] | ExtensionInfo['description'], lang?: 'zh' | 'en', fallback?: string): string;
+/**
+ * Strip known package scopes from a manifest id → flat marketplace slug.
+ * Longer scopes first so `@forgeax-extension/…` is never misread as `@forgeax/…`.
+ */
+export declare function extensionIdSlug(id: string): string;
+/** Render the browser-safe source descriptor returned by the runtime. */
+export declare function extensionManifestSourceLabel(extension: Pick<ExtensionInfo, 'id' | 'version' | 'source'>): string;
+export declare function listExtensions(kind?: string): Promise<ExtensionListResponse>;
+export declare function listExtensionsShared(opts?: {
+    force?: boolean;
+}): Promise<ExtensionListResponse>;

package/dist/package/browser/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/browser/lib/file-activity-stream.d.ts

@@ -0,0 +1,54 @@
+/** 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). */
+export interface FileLockSnapshot {
+    agentPath: string;
+    op: string;
+    since: number;
+}
+/** Wired in main.tsx alongside subscribeSessionStream. Idempotent — same
+ *  handler key, HMR-safe. */
+export declare function subscribeFileActivityStream(): void;
+/** 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 declare function useFileLocks(sid: string | null): Map<string, FileLockSnapshot>;
+/** React hook — bumps every time a file-activity:done lands for `sid`.
+ *  Plug into useEffect deps to revalidate ledger fetches without polling. */
+export declare function useFileActivityVersion(sid: string | null): number;
+/** 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 declare function dropFileActivitySession(sid: string): void;
+/** Test / debug helper — clears all in-memory state. */
+export declare function _resetFileActivityStreamForTesting(): void;
+/** 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 declare function _fileActivityStreamSessionCount(): number;
+/** 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 declare function _seedFileActivityForTest(sid: string, locks: number): void;

package/dist/package/browser/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';
+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/browser/lib/file-family.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 type FileFamily = 'code' | 'config' | 'doc' | 'scene' | 'pack' | 'meta' | 'image' | 'audio' | 'model' | 'data';
+export interface FileFamilyDefinition {
+    readonly key: FileFamily;
+    readonly label: string;
+    readonly extensions: readonly string[];
+}
+export declare const FAMILY_ORDER: readonly FileFamilyDefinition[];
+/** Classify a file path by its final extension. Unknown files are `data`. */
+export declare function familyOf(path: string): FileFamily;