@forgeax/interface 0.4.1

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

@@ -0,0 +1,2 @@
+/** Public package identity. Product startup remains on the explicit application entry. */
+export declare const INTERFACE_PACKAGE_NAME: "@forgeax/interface";

package/dist/package/browser/index.js

@@ -0,0 +1,2 @@
+/** Public package identity. Product startup remains on the explicit application entry. */
+export const INTERFACE_PACKAGE_NAME = '@forgeax/interface';

package/dist/package/browser/lib/a11y-summary.d.ts

@@ -0,0 +1,17 @@
+/** a11y-summary —— ui_snapshot 的未注册区域兜底(P1-13,评审 三.2)。
+ *
+ *  组件库自带的 role / aria-label 是免维护的 W3C 语义源:注册表管「调得动」,本模块
+ *  兜「看得见」——把 **不在 ActionRegistry 覆盖内** 的可见可交互元素汇成只读摘要,
+ *  让 AI 至少能定位「界面上还有什么」,再由人渐进登记。只读定向辅助:这些元素
+ *  **不能**经 ui_invoke 调用(契约 description 已写明)。
+ */
+export interface A11yEntry {
+    role: string;
+    label: string;
+    disabled?: boolean;
+}
+/** 汇总未注册区域的可交互元素(封顶 MAX_ENTRIES,超出标 truncated)。 */
+export declare function buildA11ySummary(): {
+    entries: A11yEntry[];
+    truncated: boolean;
+};

package/dist/package/browser/lib/a11y-summary.js

@@ -0,0 +1,66 @@
+/** a11y-summary —— ui_snapshot 的未注册区域兜底(P1-13,评审 三.2)。
+ *
+ *  组件库自带的 role / aria-label 是免维护的 W3C 语义源:注册表管「调得动」,本模块
+ *  兜「看得见」——把 **不在 ActionRegistry 覆盖内** 的可见可交互元素汇成只读摘要,
+ *  让 AI 至少能定位「界面上还有什么」,再由人渐进登记。只读定向辅助:这些元素
+ *  **不能**经 ui_invoke 调用(契约 description 已写明)。
+ */
+const INTERACTIVE_SELECTOR = [
+    'button',
+    'a[href]',
+    'input',
+    'select',
+    'textarea',
+    '[role="button"]',
+    '[role="tab"]',
+    '[role="menuitem"]',
+    '[role="checkbox"]',
+    '[role="switch"]',
+    '[role="combobox"]',
+].join(', ');
+const MAX_ENTRIES = 120;
+function roleOf(el) {
+    return el.getAttribute('role') ?? el.tagName.toLowerCase();
+}
+function labelOf(el) {
+    return (el.getAttribute('aria-label')?.trim() ||
+        el.placeholder?.trim?.() ||
+        el.getAttribute('title')?.trim() ||
+        el.textContent?.trim().slice(0, 60) ||
+        '');
+}
+function isVisible(el) {
+    // offsetParent 为 null 覆盖 display:none 与 fixed 之外的大多数隐藏;够用且便宜。
+    return el.offsetParent !== null || el.tagName === 'BODY';
+}
+/** 汇总未注册区域的可交互元素(封顶 MAX_ENTRIES,超出标 truncated)。 */
+export function buildA11ySummary() {
+    if (typeof document === 'undefined')
+        return { entries: [], truncated: false };
+    const entries = [];
+    let truncated = false;
+    const seen = new Set();
+    for (const el of document.querySelectorAll(INTERACTIVE_SELECTOR)) {
+        if (el.closest('[data-fx-action]'))
+            continue; // 已在注册表覆盖内 → 归 actions,不重复
+        if (!isVisible(el))
+            continue;
+        const label = labelOf(el);
+        if (!label)
+            continue;
+        const key = `${roleOf(el)}|${label}`;
+        if (seen.has(key))
+            continue; // 同名同角色去重(列表行等重复元素只报一次)
+        seen.add(key);
+        if (entries.length >= MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        entries.push({
+            role: roleOf(el),
+            label,
+            ...(el.disabled ? { disabled: true } : {}),
+        });
+    }
+    return { entries, truncated };
+}

package/dist/package/browser/lib/action-dom-discovery.d.ts

@@ -0,0 +1,2 @@
+/** 启动发现器(幂等)。初扫全文档 + MutationObserver 增量。 */
+export declare function startActionDomDiscovery(): void;

package/dist/package/browser/lib/action-dom-discovery.js

@@ -0,0 +1,84 @@
+/** action-dom-discovery —— data-fx-action 声明式登记的**发现器**(评审 2.4)。
+ *
+ *  职责严格限定为「发现」:带 `data-fx-action="<id>"` 的元素挂载时自动
+ *  `registerAction`(handler = click 该元素),**不构成第二条执行路径**——派发仍统一走
+ *  action-registry 的 `dispatchAction` 单入口。目标元素不在 DOM(面板没开)时
+ *  `available()` 返回人话原因 fail-closed;**不做自动导航**——「把面板打开」本身该是
+ *  一个 action(如 page.open),导航编排属于模型,不藏进派发层。
+ *
+ *  可选注解:
+ *    data-fx-title        人读标题(缺省取 aria-label / textContent)
+ *    data-fx-description  AI 读说明
+ *    data-fx-capability   权限分级(8 类之一;缺省 'other'。危险按钮**务必**标
+ *                         delete/credential,编排层会据此弹确认卡)
+ */
+import { registerAction } from './action-registry';
+const VALID_CAPS = new Set([
+    'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',
+]);
+/** id → 当前绑定的 DOM 元素(元素卸载后保留注册,available 报不可用;同 id 新元素挂载时重绑)。 */
+const boundEls = new Map();
+const registered = new Set();
+function titleFor(el, id) {
+    return (el.dataset.fxTitle?.trim() ||
+        el.getAttribute('aria-label')?.trim() ||
+        el.textContent?.trim().slice(0, 60) ||
+        id);
+}
+function bindElement(el) {
+    const id = el.dataset.fxAction?.trim();
+    if (!id)
+        return;
+    boundEls.set(id, el); // 同 id 新元素 → 重绑(注册项不变,available/run 经 map 取活引用)
+    if (registered.has(id))
+        return;
+    registered.add(id);
+    const capRaw = el.dataset.fxCapability?.trim() ?? '';
+    const capability = (VALID_CAPS.has(capRaw) ? capRaw : 'other');
+    registerAction({
+        id,
+        title: titleFor(el, id),
+        description: el.dataset.fxDescription?.trim() ||
+            `Click the "${titleFor(el, id)}" control (declared via data-fx-action).`,
+        schema: { type: 'object', properties: {} },
+        capability,
+        surface: 'ui',
+        available: () => {
+            const cur = boundEls.get(id);
+            return cur && cur.isConnected ? true : 'target element is not currently mounted (open its panel first)';
+        },
+        run: () => {
+            const cur = boundEls.get(id);
+            if (!cur || !cur.isConnected) {
+                return { status: 'rejected', reason: 'target element is not currently mounted' };
+            }
+            cur.click();
+            return { status: 'completed' };
+        },
+    });
+}
+function scan(root) {
+    if (!(root instanceof Element) && !(root instanceof Document))
+        return;
+    if (root instanceof Element && root.matches('[data-fx-action]'))
+        bindElement(root);
+    for (const el of root.querySelectorAll('[data-fx-action]'))
+        bindElement(el);
+}
+let started = false;
+/** 启动发现器(幂等)。初扫全文档 + MutationObserver 增量。 */
+export function startActionDomDiscovery() {
+    if (started || typeof document === 'undefined')
+        return;
+    started = true;
+    scan(document);
+    const mo = new MutationObserver((muts) => {
+        for (const m of muts) {
+            for (const node of m.addedNodes) {
+                if (node instanceof Element)
+                    scan(node);
+            }
+        }
+    });
+    mo.observe(document.documentElement, { childList: true, subtree: true });
+}

package/dist/package/browser/lib/action-registry.d.ts

@@ -0,0 +1,94 @@
+/** action-registry —— UI 语义操作层(产品 AI 化 P0)的单一真值源:
+ *  「本产品当前暴露哪些可被人 / AI 调用的功能」。
+ *
+ *  一张注册表服务三个消费者(压缩公理:消掉「AI 能做的和人能做的是不是同一套?」):
+ *    1. 按钮 onClick —— 组件经 `dispatchAction(id, args)` 派发(与 AI 同一条路);
+ *    2. 命令面板(P2,cmdk 激活时数据源即本表);
+ *    3. AI 工具调用 —— `ui_snapshot` 读清单 / `ui_invoke` 派发,经 lib/ui-bridge.ts
+ *       的 perception 往返接到编排层(@forgeax/orchestrator)。
+ *
+ *  契约形态(评审 2.1):`schema` 的 SSOT 是 **JSON Schema 纯对象**(AI 侧 ToolSpec 与
+ *  postMessage 结构化克隆都只吃 JSON;函数永不过 wire)。`available` / `run` 只活在
+ *  本模块,manifest(`buildManifest`)只导出可序列化子集。
+ *
+ *  headless 边界(方案 §5):`surface:'both'` 的 action,UI `run()` 必须调 server 的
+ *  同一 HTTP API(server 是行为 SSOT),UI 侧只许加视觉反馈——不许长出独立业务逻辑。
+ */
+/** 与编排层 trust-gate 的 Capability 8 类对齐(权限分级的声明值,manifest 里出墙)。 */
+export type UiCapability = 'read' | 'write' | 'delete' | 'exec' | 'network' | 'credential' | 'delegate' | 'other';
+/** 派发结果(评审 2.2 act→observe 合并):
+ *  - completed:已完成,`stateDigest` 携带可观察的状态变化(多数场景免掉后续 snapshot);
+ *  - accepted:已受理、异步在跑(慢 action 快速返回,勿等勿重试;P0 期完成态靠下次 snapshot 观察);
+ *  - rejected:未执行,`reason` 给人话原因(未注册 / 不可用 / 参数校验失败 / run 抛错)。 */
+export interface UiActionResult {
+    status: 'completed' | 'accepted' | 'rejected';
+    reason?: string;
+    stateDigest?: unknown;
+}
+/** JSON Schema 纯对象(不引 zod 类型;zod 只是书写便利,登记时即转换落表)。 */
+export type JsonSchemaObject = Record<string, unknown>;
+export interface UiActionDef {
+    /** 稳定 id,'domain.verb' 形("game.switch" / "panel.toggle_sidebar")。 */
+    id: string;
+    /** 人读标题(菜单 / 命令面板 / 权限卡展示)。 */
+    title: string;
+    /** AI 读说明(manifest 出墙;写清做什么 + 何时用)。 */
+    description?: string;
+    /** 参数契约(JSON Schema 纯对象)。缺省 = 无参数。 */
+    schema?: JsonSchemaObject;
+    /** 权限分级声明 —— 编排层 trust-gate 按此弹卡/直放(delete/credential 会请求用户确认)。 */
+    capability: UiCapability;
+    /** headless 可用性:'ui'(纯视图,须 UI 在线)/ 'server'/'both'(状态型,server 是 SSOT)。 */
+    surface?: 'ui' | 'server' | 'both';
+    /** 预期执行时长(ms)——编排层往返超时据此放宽;慢 action 的正道是快速回 accepted。 */
+    timeoutMs?: number;
+    /** 当前是否可调。返回 string = 不可用 + 人话原因(AI 可读可解释);缺省恒可用。 */
+    available?: () => true | string;
+    /** P1-9 一等工具化:标 true → 编排层从 manifest 派生独立 ToolSpec(ui_act_*)下发
+     *  模型,免一次 snapshot 发现往返。只给高频 action 打标(编排层有数量上限)。 */
+    firstClass?: boolean;
+    /** 「人」界面(命令面板)用的**动态候选值**提供器,按参数名给一列合法取值 —— 让
+     *  自由文本参数(如 game.switch 的 slug)变成下拉,避免瞎填后触发 server 404。
+     *  仅活在客户端(同 run/available,不进 manifest);AI 侧靠 ui_snapshot / 状态片发现,
+     *  不依赖此。静态 `schema.enum` 优先于此(两者都无则退回文本框)。 */
+    choices?: Record<string, () => string[] | Promise<string[]>>;
+    /** 执行体。返回 void 视为 completed;抛错翻成 rejected(fail-soft,不炸往返)。 */
+    run: (args: Record<string, unknown>) => UiActionResult | void | Promise<UiActionResult | void>;
+}
+/** snapshot 状态摘要的一片(评审 2.5:注册式 derive,禁手写台账)。selector 从 store
+ *  等真值源读,值必须可序列化(过 JSON.stringify)。 */
+export type StateSliceSelector = () => unknown;
+/** 注册一个 action(同 id 重复注册 = 替换,幂等;HMR 安全)。返回注销函数。 */
+export declare function registerAction(def: UiActionDef): () => void;
+/** 注册一片状态摘要(同 id 替换,幂等)。返回注销函数。 */
+export declare function registerStateSlice(id: string, selector: StateSliceSelector): () => void;
+/** 注册表(action 或 state slice)变更订阅 —— ui-bridge 据此 debounce 重推 manifest。 */
+export declare function onRegistryChange(cb: () => void): () => void;
+export declare function getAction(id: string): UiActionDef | undefined;
+/** AI 派发时打的来源标记;window 事件供 ghost 高亮层(P1)与 telemetry / 轨迹追踪衔接。
+ *  detail 形:`{ id, source, args }` —— args 让轨迹追踪(lib/ui-trajectory)记得下「做了啥」,
+ *  ghost 高亮只用 id/source(向后兼容,多带的字段无害)。 */
+export declare const UI_ACTION_DISPATCH_EVENT = "forgeax:ui-action-dispatch";
+/** 派发一个 action —— 按钮与 AI 共用的**唯一**执行入口(未注册的 id 拒绝,fail-closed)。 */
+export declare function dispatchAction(id: string, args?: Record<string, unknown>, opts?: {
+    source?: 'human' | 'ai';
+}): Promise<UiActionResult>;
+export interface UiActionSummary {
+    id: string;
+    title: string;
+    available: boolean;
+    reason?: string;
+    /** detail:'schema' 时补上。 */
+    description?: string;
+    inputSchema?: JsonSchemaObject;
+}
+/** ui_snapshot 的 action 视图。分层(评审 2.7):默认轻量清单;detail:'schema' + ids
+ *  按需展开 schema 与详细说明(长尾几百 action 也不炸 token)。 */
+export declare function snapshotActions(detail?: string, ids?: string[]): UiActionSummary[];
+/** ui_snapshot 的状态摘要:逐片 derive,单片异常不传染(fail-soft)。 */
+export declare function snapshotState(): Record<string, unknown>;
+/** manifest(POST /:sid/ui-manifest 的 payload)—— 只含可序列化声明,函数永不出墙。
+ *  它是编排层 trust-gate 的权限输入:capability 必须如实声明。 */
+export declare function buildManifest(): Array<Record<string, unknown>>;
+/** 测试用:清空注册表(生产代码不要调)。 */
+export declare function __resetRegistryForTest(): void;

package/dist/package/browser/lib/action-registry.js

@@ -0,0 +1,210 @@
+/** action-registry —— UI 语义操作层(产品 AI 化 P0)的单一真值源:
+ *  「本产品当前暴露哪些可被人 / AI 调用的功能」。
+ *
+ *  一张注册表服务三个消费者(压缩公理:消掉「AI 能做的和人能做的是不是同一套?」):
+ *    1. 按钮 onClick —— 组件经 `dispatchAction(id, args)` 派发(与 AI 同一条路);
+ *    2. 命令面板(P2,cmdk 激活时数据源即本表);
+ *    3. AI 工具调用 —— `ui_snapshot` 读清单 / `ui_invoke` 派发,经 lib/ui-bridge.ts
+ *       的 perception 往返接到编排层(@forgeax/orchestrator)。
+ *
+ *  契约形态(评审 2.1):`schema` 的 SSOT 是 **JSON Schema 纯对象**(AI 侧 ToolSpec 与
+ *  postMessage 结构化克隆都只吃 JSON;函数永不过 wire)。`available` / `run` 只活在
+ *  本模块,manifest(`buildManifest`)只导出可序列化子集。
+ *
+ *  headless 边界(方案 §5):`surface:'both'` 的 action,UI `run()` 必须调 server 的
+ *  同一 HTTP API(server 是行为 SSOT),UI 侧只许加视觉反馈——不许长出独立业务逻辑。
+ */
+// ─── 注册表本体(模块级 Map,页级单例)────────────────────────────────────────
+const actions = new Map();
+const stateSlices = new Map();
+const changeListeners = new Set();
+function notifyChange() {
+    for (const cb of changeListeners) {
+        try {
+            cb();
+        }
+        catch {
+            /* listener 异常不传染 */
+        }
+    }
+}
+/** 注册一个 action(同 id 重复注册 = 替换,幂等;HMR 安全)。返回注销函数。 */
+export function registerAction(def) {
+    actions.set(def.id, def);
+    notifyChange();
+    return () => {
+        if (actions.get(def.id) === def) {
+            actions.delete(def.id);
+            notifyChange();
+        }
+    };
+}
+/** 注册一片状态摘要(同 id 替换,幂等)。返回注销函数。 */
+export function registerStateSlice(id, selector) {
+    stateSlices.set(id, selector);
+    notifyChange();
+    return () => {
+        if (stateSlices.get(id) === selector) {
+            stateSlices.delete(id);
+            notifyChange();
+        }
+    };
+}
+/** 注册表(action 或 state slice)变更订阅 —— ui-bridge 据此 debounce 重推 manifest。 */
+export function onRegistryChange(cb) {
+    changeListeners.add(cb);
+    return () => changeListeners.delete(cb);
+}
+export function getAction(id) {
+    return actions.get(id);
+}
+// ─── 派发单入口(评审 2.4:data-* 只做发现,执行永远走这里)──────────────────
+/** AI 派发时打的来源标记;window 事件供 ghost 高亮层(P1)与 telemetry / 轨迹追踪衔接。
+ *  detail 形:`{ id, source, args }` —— args 让轨迹追踪(lib/ui-trajectory)记得下「做了啥」,
+ *  ghost 高亮只用 id/source(向后兼容,多带的字段无害)。 */
+export const UI_ACTION_DISPATCH_EVENT = 'forgeax:ui-action-dispatch';
+/** 极简 JSON Schema 参数校验(P0:required + 顶层 properties 的原始类型)。
+ *  不引 ajv——契约漂移由编排层契约测试兜,这里挡住明显错参即可(Fail Fast)。 */
+function validateArgs(schema, args) {
+    if (!schema)
+        return true;
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const k of required) {
+        if (typeof k === 'string' && !(k in args))
+            return `missing required arg "${k}"`;
+    }
+    const props = schema.properties && typeof schema.properties === 'object'
+        ? schema.properties
+        : {};
+    for (const [k, v] of Object.entries(args)) {
+        const p = props[k];
+        if (!p)
+            continue; // 未声明的多余参数放过(向前兼容),由 run 自行忽略
+        const t = p.type;
+        if (typeof t === 'string') {
+            const actual = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
+            const okType = (t === 'string' && actual === 'string') ||
+                (t === 'number' && actual === 'number') ||
+                (t === 'integer' && actual === 'number' && Number.isInteger(v)) ||
+                (t === 'boolean' && actual === 'boolean') ||
+                (t === 'object' && actual === 'object') ||
+                (t === 'array' && actual === 'array');
+            if (!okType)
+                return `arg "${k}" should be ${t}, got ${actual}`;
+        }
+        if (Array.isArray(p.enum) && !p.enum.includes(v)) {
+            return `arg "${k}" must be one of ${JSON.stringify(p.enum)}`;
+        }
+    }
+    return true;
+}
+/** 派发一个 action —— 按钮与 AI 共用的**唯一**执行入口(未注册的 id 拒绝,fail-closed)。 */
+export async function dispatchAction(id, args = {}, opts = {}) {
+    const src = opts.source ?? 'human';
+    // [fx-action-trace] 定位「点了/调了没反应」的最小充分打点:
+    //   ① entry —— 派发是否发生 + args/source(缺此行 = 根本没触发 dispatch)。
+    //   ② terminal —— 唯一终态行:completed/accepted 带 stateDigest(判「到底改了啥」),
+    //      rejected 带 reason(未注册/不可用/参数错/run 抛错 已统一收敛进 reason)。
+    // 两行即可定位:有 entry 无 terminal = 卡在 run();rejected+reason = 为何被拒;
+    // completed 但 stateDigest 没变 = action 效果与 UI 脱节。故只留这两点(+抛错补栈)。
+    console.info(`%c[fx-action]%c ▶ ${id} (${src})`, 'color:#818cf8;font-weight:bold', 'color:inherit', { args });
+    const done = (r) => {
+        if (r.status === 'rejected') {
+            console.warn(`[fx-action] ✗ ${id} rejected: ${r.reason ?? ''}`);
+        }
+        else {
+            console.info(`%c[fx-action]%c ✔ ${id} → ${r.status}`, 'color:#34d399;font-weight:bold', 'color:inherit', r.stateDigest !== undefined ? { stateDigest: r.stateDigest } : {});
+        }
+        return r;
+    };
+    const def = actions.get(id);
+    if (!def)
+        return done({ status: 'rejected', reason: `unknown action "${id}" (not in the registry)` });
+    const avail = def.available ? safeAvailable(def) : true;
+    if (avail !== true)
+        return done({ status: 'rejected', reason: avail });
+    const valid = validateArgs(def.schema, args);
+    if (valid !== true)
+        return done({ status: 'rejected', reason: valid });
+    try {
+        window.dispatchEvent(new CustomEvent(UI_ACTION_DISPATCH_EVENT, { detail: { id, source: src, args } }));
+    }
+    catch {
+        /* SSR / no window — ignore */
+    }
+    try {
+        const out = await def.run(args);
+        return done(out ?? { status: 'completed' });
+    }
+    catch (e) {
+        console.error(`[fx-action] ✗ ${id} threw`, e); // 抛错补一行栈(定位真异常)
+        return done({ status: 'rejected', reason: `action "${id}" threw: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+function safeAvailable(def) {
+    try {
+        return def.available();
+    }
+    catch (e) {
+        return `availability check threw: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/** ui_snapshot 的 action 视图。分层(评审 2.7):默认轻量清单;detail:'schema' + ids
+ *  按需展开 schema 与详细说明(长尾几百 action 也不炸 token)。 */
+export function snapshotActions(detail, ids) {
+    const expand = detail === 'schema' ? new Set(ids ?? []) : null;
+    const out = [];
+    for (const def of actions.values()) {
+        const avail = def.available ? safeAvailable(def) : true;
+        const row = {
+            id: def.id,
+            title: def.title,
+            available: avail === true,
+            ...(avail === true ? {} : { reason: avail }),
+        };
+        if (expand?.has(def.id)) {
+            if (def.description)
+                row.description = def.description;
+            row.inputSchema = def.schema ?? { type: 'object', properties: {} };
+        }
+        out.push(row);
+    }
+    return out;
+}
+/** ui_snapshot 的状态摘要:逐片 derive,单片异常不传染(fail-soft)。 */
+export function snapshotState() {
+    const out = {};
+    for (const [id, selector] of stateSlices) {
+        try {
+            out[id] = selector();
+        }
+        catch (e) {
+            out[id] = { error: `state slice threw: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    return out;
+}
+/** manifest(POST /:sid/ui-manifest 的 payload)—— 只含可序列化声明,函数永不出墙。
+ *  它是编排层 trust-gate 的权限输入:capability 必须如实声明。 */
+export function buildManifest() {
+    const out = [];
+    for (const def of actions.values()) {
+        out.push({
+            id: def.id,
+            title: def.title,
+            ...(def.description ? { description: def.description } : {}),
+            inputSchema: def.schema ?? { type: 'object', properties: {} },
+            capability: def.capability,
+            ...(def.surface ? { surface: def.surface } : {}),
+            ...(def.timeoutMs ? { timeoutMs: def.timeoutMs } : {}),
+            ...(def.firstClass ? { firstClass: true } : {}),
+        });
+    }
+    return out;
+}
+/** 测试用:清空注册表(生产代码不要调)。 */
+export function __resetRegistryForTest() {
+    actions.clear();
+    stateSlices.clear();
+    changeListeners.clear();
+}

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

@@ -0,0 +1,40 @@
+/** Minimal surface of the Aegis instance we actually call. */
+interface AegisInstance {
+    error(payload: unknown): void;
+    info(payload: unknown): void;
+    report(payload: unknown): void;
+    setConfig(config: Record<string, unknown>): void;
+    destroy(): void;
+}
+type AegisCtor = new (config: Record<string, unknown>) => AegisInstance;
+declare global {
+    interface Window {
+        Aegis?: AegisCtor;
+        __forgeaxAegis?: AegisInstance;
+    }
+}
+/**
+ * Boot Aegis if — and only if — a project token is configured AND this is a
+ * production build. dev (`bun dev`) deliberately stays silent to keep the
+ * Galileo dataset clean; verify the wiring with `bun run build && bun run
+ * preview` (preview is a PROD build) or in the deployed web / desktop .app.
+ *
+ * Idempotent: StrictMode double-invokes and the two boot paths in main.tsx
+ * (detached surface + full shell) can both call this; the `started` latch makes
+ * the second call a no-op.
+ */
+export declare function initAegis(): void;
+/**
+ * Report a React-render error. React error boundaries swallow render throws
+ * before they reach window.onerror, so Aegis' auto JS-error capture never sees
+ * them — this bridges that gap. No-op until the SDK instance is live (early
+ * pre-load boundary catches are rare and still surface in the console).
+ */
+export declare function reportError(error: Error, componentStack?: string | null, scope?: string): void;
+/**
+ * Attach the current user's id once known. uid is often not available at boot,
+ * so call this after auth/session resolves; Aegis backfills it on every
+ * subsequent report. No-op until the SDK instance is live.
+ */
+export declare function setAegisUid(uid: string): void;
+export {};