wu-framework 2.1.1 → 2.5.0

package/dist/index.d.cts

@@ -0,0 +1,739 @@
+// Wu Framework - Type Declarations (v2.0)
+// AI classes moved to 'wu-framework/ai' subpath.
+// Sandbox internals moved to 'wu-framework/sandbox/*' subpaths.
+
+// --- Core Types ---
+
+export interface WuEvent {
+  name: string;
+  data: any;
+  timestamp: number;
+  appName: string;
+  meta: Record<string, any>;
+  verified: boolean;
+}
+
+export interface WuAppConfig {
+  name: string;
+  url: string;
+  container?: string;
+  keepAlive?: boolean;
+  sandbox?: 'module' | 'strict' | 'eval';
+  /**
+   * Per-app override for `strict` mode CORS fallback (v2.1+).
+   * - `true` (default): degrade to `eval` on iframe import failure with a warning
+   * - `false`: throw on failure instead
+   */
+  strictFallback?: boolean;
+  /**
+   * CSS isolation mode. v2.1 aliases:
+   * - `none` is an alias for `isolated`
+   * - `own-only` is an alias for `fully-isolated`
+   */
+  styleMode?: 'shared' | 'isolated' | 'fully-isolated' | 'none' | 'own-only';
+}
+
+/**
+ * Runtime sandbox info reported by `wu.getSandboxInfo(appName)` (v2.1+).
+ */
+export interface WuSandboxInfo {
+  /** What the caller asked for (from app config or global init) */
+  requestedMode: 'module' | 'strict' | 'eval';
+  /** What's actually running. Differs from requestedMode if strict fell back to eval. */
+  actualMode: 'module' | 'strict' | 'eval';
+  /** Human-readable isolation tier */
+  isolationLevel: 'none' | 'iframe' | 'proxy-trap';
+  /** Whether the app is currently mounted (vs hidden via keep-alive) */
+  mounted: boolean;
+}
+
+export interface WuLifecycle {
+  mount: (container: HTMLElement) => void | Promise<void>;
+  unmount?: (container: HTMLElement) => void | Promise<void>;
+  activate?: (container: HTMLElement) => void | Promise<void>;
+  deactivate?: (container: HTMLElement) => void | Promise<void>;
+  /**
+   * Live-props slot (v2.2+). Called by `wu.update(appName, props)` to push new
+   * props into a mounted app without remounting. Adapters built on
+   * `createWuAdapter` expose this when their framework can re-render in place.
+   */
+  update?: (container: HTMLElement, props: Record<string, any>) => void | Promise<void>;
+}
+
+/** Full-page diagnostic snapshot returned by `wu.inspect()` (v2.2+). */
+export interface WuInspectSnapshot {
+  version: string | null;
+  timestamp: number;
+  summary: { registered: number; defined: number; mounted: number; hidden: number };
+  apps: Array<{
+    name: string;
+    status: 'mounted' | 'hidden';
+    framework: string | null;
+    containerSelector: string | null;
+    mountedAt: number | null;
+    liveProps: boolean;
+    props: Record<string, any> | null;
+    sandbox: WuSandboxInfo | null;
+  }>;
+  defined: string[];
+  registered: string[];
+  /** Registered capability contracts (v2.5+). */
+  capabilities: Array<{ name: string; version: string; app: string | null }>;
+  events: { recent: Array<{ type: string; appName?: string; timestamp?: number }>; stats: any };
+  store: { snapshot: any; metrics: any };
+}
+
+/** Options for `wu.provide()` (v2.5+). */
+export interface WuProvideOptions {
+  /** Semver version the implementation satisfies (default '0.0.0'). */
+  version?: string;
+  /** Required keys (array) or key→typeof map; verified at provide() time. */
+  shape?: string[] | Record<string, string>;
+  /** Providing app — the capability auto-revokes when this app unmounts. */
+  app?: string;
+}
+
+/** Options for `wu.consume()` (v2.5+). */
+export interface WuConsumeOptions {
+  /** Return a Promise that resolves once a satisfying provider appears. */
+  wait?: boolean;
+  /** ms; rejects the wait promise if exceeded. */
+  timeout?: number;
+}
+
+/** Handle returned by `wu.provide()` (v2.5+). */
+export interface WuCapabilityHandle {
+  revoke(): void;
+}
+
+/**
+ * Typed, versioned, runtime-verified capability contracts (v2.5+). Apps
+ * declare what they provide and consume; the runtime negotiates semver and
+ * verifies shape — replacing Module Federation's fragile shared singletons.
+ */
+export class WuContracts {
+  constructor(core: WuCore);
+  provide<T extends object>(name: string, impl: T, opts?: WuProvideOptions): WuCapabilityHandle;
+  consume<T = any>(name: string, range?: string, opts?: { wait?: false; timeout?: number }): T;
+  consume<T = any>(name: string, range: string, opts: { wait: true; timeout?: number }): Promise<T>;
+  has(name: string, range?: string): boolean;
+  revoke(name: string): boolean;
+  list(): Array<{ name: string; version: string; app: string | null }>;
+  cleanup(): void;
+}
+
+/** A single journal entry recorded by WuTimeline (v2.3+). */
+export interface WuTimelineEntry {
+  /** Lamport clock — the (l, site) pair is the CRDT total order. */
+  l: number;
+  /** Originating site id. */
+  site: string;
+  /** Wall-clock timestamp (ms). */
+  t: number;
+  kind: 'store' | 'event';
+  /** store: ring-buffer sequence number */
+  seq?: number;
+  /** store: dot-path written ('' = full-state replace) */
+  path?: string;
+  /** store: written value (deep-cloned) */
+  value?: any;
+  /** event: event name */
+  name?: string;
+  /** event: source app */
+  appName?: string;
+  /** event (app:mounted): container selector */
+  container?: string | null;
+  /** event (app:updated): live props pushed */
+  props?: Record<string, any> | null;
+}
+
+/** Status of the time-travel recorder (v2.3+). */
+export interface WuTimelineStatus {
+  loaded: boolean;
+  recording: boolean;
+  /** true when positioned at the journal end (the present) */
+  live: boolean;
+  /** number of journal entries applied */
+  position: number;
+  /** total journal length */
+  length: number;
+  site: string | null;
+  lamport: number;
+  snapshots: number;
+}
+
+/** Serializable journal — the reproducible bug report (v2.3+). */
+export interface WuTimelineExport {
+  format: string;
+  wu: string | null;
+  site: string;
+  exportedAt: number;
+  baselineApps: Array<{ name: string; container: string | null; props: Record<string, any> | null }>;
+  entries: WuTimelineEntry[];
+  snapshots: Array<{ at: number; state: any }>;
+}
+
+/**
+ * The `wu.timeline` facade (v2.3+) — cross-framework time travel. Records every
+ * store write, event-bus emit, and app lifecycle change into one journal;
+ * seek() rewinds the whole multi-framework page in lockstep (store hydrate +
+ * live-props replay + app diff). Synchronous + chainable for the fire-and-forget
+ * controls (record/stop/clear); the seek family returns Promises. The recorder
+ * chunk is lazy-loaded on first use — `await wu.timelineReady()` to force it.
+ * See ROADMAP.md.
+ */
+export interface WuTimelineFacade {
+  record(opts?: { snapshotEvery?: number; maxEntries?: number }): WuTimelineFacade;
+  stop(): WuTimelineFacade;
+  clear(): WuTimelineFacade;
+  /** Rewind/forward to a journal position (0..length). */
+  seek(pos: number, opts?: { store?: boolean; apps?: boolean; props?: boolean }): Promise<WuTimelineStatus>;
+  /** Return to the present (seek to journal end). */
+  live(): Promise<WuTimelineStatus>;
+  stepBack(): Promise<WuTimelineStatus>;
+  stepForward(): Promise<WuTimelineStatus>;
+  export(): Promise<WuTimelineExport>;
+  import(data: WuTimelineExport): Promise<WuTimelineStatus>;
+  /** Merge remote journal entries (CRDT seed for multiplayer sync, #2). */
+  ingest(remoteEntries: WuTimelineEntry[]): Promise<WuTimelineStatus>;
+  entries(): WuTimelineEntry[];
+  status(): WuTimelineStatus;
+  readonly loaded: boolean;
+  /** The underlying WuTimeline instance once loaded (lazy), else null. */
+  readonly instance: any;
+}
+
+/** A duck-typed sync transport (v2.4+). Bring your own, or use 'broadcast' / a WebSocket. */
+export interface WuSyncTransport {
+  send(message: any): void;
+  onMessage(cb: (message: any) => void): void;
+  close(): void;
+}
+
+/** Options for `wu.store.sync()` (v2.4+). */
+export interface WuSyncOptions {
+  /** 'broadcast' (cross-tab), a WebSocket / ws(s):// URL, or a custom transport. Default 'broadcast'. */
+  transport?: 'broadcast' | WuSyncTransport | WebSocket | string;
+  /** Channel name for the broadcast transport. Default 'default'. */
+  room?: string;
+}
+
+/** Live status of a store-sync session (v2.4+). */
+export interface WuSyncStatus {
+  connected: boolean;
+  site: string | null;
+  lamport: number;
+  peers: number;
+  tracked?: number;
+  sent?: number;
+  received?: number;
+  applied?: number;
+  ignored?: number;
+  /** Local writes skipped because the value wasn't serializable. */
+  dropped?: number;
+  loading?: boolean;
+  stopped?: boolean;
+  /** Set if the connection failed (e.g. unknown transport). */
+  error?: string | null;
+}
+
+/** Handle returned by `wu.store.sync()` (v2.4+). */
+export interface WuSyncHandle {
+  /** Stop syncing — detaches the store tap and closes the transport. */
+  stop(): void;
+  status(): WuSyncStatus;
+  /** Resolves once the sync chunk has loaded and the transport is connected. */
+  ready(): Promise<any>;
+  readonly connected: boolean;
+  readonly instance: any;
+}
+
+export interface WuPlugin {
+  name: string;
+  permissions?: Array<'mount' | 'events' | 'store' | 'apps' | 'config' | 'unsafe'>;
+  install?: (api: WuSandboxedApi, options?: any) => void;
+  uninstall?: (api: WuSandboxedApi) => void;
+  beforeInit?: (context: any) => void | Promise<void>;
+  afterInit?: (context: any) => void | Promise<void>;
+  beforeMount?: (context: any) => void | boolean | Promise<void | boolean>;
+  afterMount?: (context: any) => void | Promise<void>;
+  beforeUnmount?: (context: any) => void | Promise<void>;
+  afterUnmount?: (context: any) => void | Promise<void>;
+  onError?: (context: any) => void | Promise<void>;
+  onDestroy?: (context: any) => void | Promise<void>;
+}
+
+export interface WuSandboxedApi {
+  version: string;
+  info: { name: string; description: string; features: string[] };
+  getAppInfo(appName: string): { name: string; state: string; timestamp: number } | null;
+  getMountedApps(): string[];
+  getStats(): Record<string, any>;
+  emit?(event: string, data: any): boolean;
+  on?(event: string, cb: (event: WuEvent) => void): () => void;
+  off?(event: string, cb: (event: WuEvent) => void): void;
+  getState?(path: string): any;
+  setState?(path: string, value: any): number;
+  mount?(appName: string, container: string): Promise<void>;
+  unmount?(appName: string): Promise<void>;
+}
+
+// --- AI Lazy Proxy ---
+// The wu.ai property is a Proxy backed by a lazy-loaded chunk. Methods that
+// return `this` for chaining work synchronously (calls are queued and flushed
+// after the chunk loads). Async methods return Promises/AsyncGenerators that
+// await the load transparently. Use `wu.aiReady()` to get the real instance.
+
+export interface WuAILazyProxy {
+  readonly isLazy: true;
+  readonly isLoaded: false;
+
+  // Chainable config (sync, queued — return the proxy for chaining)
+  provider(name: string, config: any): WuAILazyProxy;
+  action(name: string, config: any): WuAILazyProxy;
+  trigger(name: string, config: any): WuAILazyProxy;
+  capability(appName: string, actionName: string, config: any): WuAILazyProxy;
+  workflow(name: string, config: any): WuAILazyProxy;
+  removeApp(appName: string): WuAILazyProxy;
+  init(config?: any): WuAILazyProxy;
+
+  // Async — load chunk + delegate
+  send(message: string, options?: any): Promise<any>;
+  json(message: string, options?: any): Promise<any>;
+  intent(description: string, options?: any): Promise<any>;
+  execute(name: string, params: any): Promise<any>;
+  fireTrigger(name: string, eventData?: any): Promise<any>;
+
+  // Async generators
+  stream(message: string, options?: any): AsyncGenerator<any>;
+  agent(goal: string, options?: any): AsyncGenerator<any>;
+  runWorkflow(name: string, params?: any, options?: any): AsyncGenerator<any>;
+
+  // Sync-returning (faux defaults before load, real values after)
+  tools(): any[];
+  expose(): boolean;
+  getStats(): Record<string, any>;
+
+  // Sync void (queued)
+  abort(namespace?: string): void;
+  destroy(): void;
+  confirmTool(callId: string): void;
+  rejectTool(callId: string): void;
+
+  // Sub-objects
+  context: WuAISubProxy;
+  conversation: WuAISubProxy;
+  permissions: WuAISubProxy;
+}
+
+export interface WuAISubProxy {
+  [method: string]: (...args: any[]) => any;
+}
+
+// --- Core Classes ---
+
+export class WuCore {
+  apps: Map<string, any>;
+  mounted: Map<string, any>;
+  hidden: Map<string, any>;
+  eventBus: WuEventBus;
+  store: WuStore;
+  pluginSystem: WuPluginSystem;
+  hooks: WuLifecycleHooks;
+  performance: WuPerformance;
+  prefetcher: WuPrefetch;
+  overrides: WuOverrides;
+  errorBoundary: WuErrorBoundary;
+  sandbox: WuSandbox;
+  cache: WuCache;
+  /** Capability-contract registry (v2.5+). */
+  contracts: WuContracts;
+
+  /**
+   * Lazy AI proxy. Auto-loads the AI chunk on first method call.
+   * Use `wu.aiReady()` to await the load explicitly.
+   */
+  readonly ai: WuAILazyProxy;
+  /** Resolve to the real WuAI instance (chunk loaded). */
+  aiReady(): Promise<any>;
+
+  /** MCP bridge for connecting to wu-mcp-server. */
+  mcp: {
+    connect(url?: string, options?: any): Promise<void>;
+    disconnect(): void;
+    isConnected(): boolean;
+  };
+
+  init(config: {
+    apps: WuAppConfig[];
+    sandbox?: 'module' | 'strict' | 'eval';
+    /** v2.1+: global default for whether strict mode degrades to eval on CORS */
+    strictFallback?: boolean;
+    overrides?: any;
+  }): Promise<void>;
+  mount(appName: string, containerSelector: string): Promise<void>;
+  unmount(appName: string, options?: { force?: boolean; keepAlive?: boolean }): Promise<void>;
+  /**
+   * Push new props into an already-mounted app without remounting (v2.2+).
+   * Resolves `true` if the app's adapter supports live props; resolves `false`
+   * (an honest no-op, never throws) when the app is not mounted or its adapter
+   * has no `update` slot.
+   */
+  update(appName: string, props: Record<string, any>): Promise<boolean>;
+  define(appName: string, lifecycle: WuLifecycle): void;
+  app(name: string, config: Partial<WuAppConfig>): WuApp;
+  hide(appName: string): Promise<void>;
+  show(appName: string): Promise<void>;
+  isHidden(appName: string): boolean;
+  destroy(): Promise<void>;
+  getStats(): Record<string, any>;
+
+  /**
+   * Inspect the actual JS isolation level for a mounted app (v2.1+).
+   * Useful to verify that `strict` didn't silently degrade to `eval` after
+   * a CORS failure.
+   */
+  getSandboxInfo(appName: string): WuSandboxInfo | null;
+
+  /**
+   * Register a capability another app can consume (typed/versioned contract, v2.5+).
+   */
+  provide<T extends object>(name: string, impl: T, opts?: WuProvideOptions): WuCapabilityHandle;
+  /**
+   * Consume a capability from another app (v2.5+). Returns a live proxy that
+   * fails loudly on access if unsatisfied, or a Promise with { wait: true }.
+   */
+  consume<T = any>(name: string, range?: string, opts?: { wait?: false; timeout?: number }): T;
+  consume<T = any>(name: string, range: string, opts: { wait: true; timeout?: number }): Promise<T>;
+
+  /**
+   * Full-page diagnostic snapshot — every mounted app, its sandbox mode and
+   * live-props capability, recent events, and a store snapshot in one object
+   * (v2.2+). Backs `wu.showInspector()` and `window.__WU_DEVTOOLS__`.
+   */
+  inspect(opts?: { events?: number }): WuInspectSnapshot;
+
+  /** Open the lazy, Shadow-DOM-isolated inspector overlay (v2.2+). */
+  showInspector(): Promise<{ close: () => void } | null>;
+  /** Close the inspector overlay if open (v2.2+). */
+  hideInspector(): Promise<void>;
+
+  /**
+   * Cross-framework time travel (v2.3+). Record store/event/lifecycle
+   * mutations and scrub the whole multi-framework page back and forth. The
+   * recorder is a lazy chunk loaded on first `wu.timeline.*` call — zero
+   * overhead until used. See ROADMAP.md.
+   */
+  timeline: WuTimelineFacade;
+
+  /**
+   * Force-load the timeline chunk and resolve the real WuTimeline (v2.3+).
+   * `await wu.timelineReady()` before the first write you want captured — after
+   * it resolves, `wu.timeline.record()` arms synchronously. Mirrors aiReady().
+   */
+  timelineReady(): Promise<any>;
+
+  /**
+   * Tag a <style> or <link> element as belonging to a specific app (v2.1+).
+   * Makes `fully-isolated` / `own-only` styleMode detect the style regardless
+   * of bundler. Necessary for webpack / esbuild / plain HTML apps; Vite is
+   * detected automatically.
+   */
+  tagStyleAsApp(el: HTMLElement, appName: string): void;
+
+  // Convenience proxies
+  emit(event: string, data?: any, opts?: any): boolean;
+  on(event: string, cb: (event: WuEvent) => void): () => void;
+  once(event: string, cb: (event: WuEvent) => void): () => void;
+  off(event: string, cb: (event: WuEvent) => void): void;
+  prefetch(appNames: string | string[], opts?: any): Promise<void> | (() => void);
+  prefetchAll(opts?: any): Promise<void> | (() => void);
+  override(name: string, url: string, opts?: any): void;
+  removeOverride(name: string): void;
+  getOverrides(): Record<string, string>;
+  clearOverrides(): void;
+  silence(): Promise<void>;
+  verbose(): Promise<void>;
+
+  version: string;
+  info: { name: string; description: string; features: string[] };
+}
+
+export class WuEventBus {
+  constructor();
+  authorizedApps: Map<string, any>;
+  trustedEvents: Set<string>;
+  trustedApps: Set<string>;
+  history: WuEvent[];
+
+  emit(eventName: string, data?: any, options?: { appName?: string; token?: string; meta?: any; history?: boolean }): boolean;
+  on(eventName: string, callback: (event: WuEvent) => void): () => void;
+  once(eventName: string, callback: (event: WuEvent) => void): () => void;
+  off(eventName: string, callback: (event: WuEvent) => void): void;
+  registerApp(appName: string, options?: { permissions?: string[]; token?: string }): string;
+  unregisterApp(appName: string): void;
+  replay(eventNameOrPattern: string, callback: (event: WuEvent) => void): void;
+  clearHistory(eventNameOrPattern?: string): void;
+  matchesWildcard(eventName: string, pattern: string): boolean;
+  /**
+   * Low-level emit tap (v2.3+). Fires for every emitted event (after history,
+   * before listeners), bypassing wildcard matching and authorization — the
+   * internal firehose WuTimeline journals from. Returns an unsubscribe fn.
+   */
+  tap(fn: (event: WuEvent) => void): () => void;
+  enableStrictMode(): void;
+  disableStrictMode(): void;
+  removeAll(): void;
+  getStats(): Record<string, any>;
+  configure(config: Partial<Record<string, any>>): void;
+}
+
+export class WuStore {
+  constructor(bufferSize?: number);
+  get(path?: string): any;
+  /** Throws on unsafe keys (__proto__, constructor, prototype). */
+  set(path: string, value: any): number;
+  on(pattern: string, callback: (value: any, path?: string) => void): () => void;
+  batch(updates: Record<string, any>): number[];
+  /**
+   * Low-level write tap (v2.3+). Fires synchronously inside set() for every
+   * write with the ring-buffer sequence — the substrate WuTimeline journals
+   * from. Returns an unsubscribe function.
+   */
+  tap(fn: (sequence: number, path: string, value: any) => void): () => void;
+  /**
+   * Replace the whole state and re-notify listeners (v2.3+) — the seek
+   * primitive for WuTimeline. Does not touch the ring buffer or taps.
+   */
+  hydrate(newState: any, opts?: { notifyPaths?: string[] }): void;
+  /**
+   * Start real-time collaborative sync across replicas (tabs/workers/clients)
+   * via a per-path Last-Writer-Wins CRDT (v2.4+). Lazy-loads the sync chunk.
+   * See ROADMAP.md (#2).
+   */
+  sync(opts?: WuSyncOptions): WuSyncHandle;
+  clear(): void;
+  getMetrics(): {
+    reads: number;
+    writes: number;
+    notifications: number;
+    bufferUtilization: number;
+    sequenceNumber: number;
+    bufferSize: number;
+    listenerCount: number;
+  };
+}
+
+export class WuLoader {
+  constructor(options?: { maxCacheSize?: number; cacheTTL?: number });
+  loadApp(appUrl: string, manifest?: any): Promise<string>;
+  loadComponent(appUrl: string, componentPath: string): Promise<any>;
+  preload(appConfigs: WuAppConfig[]): Promise<void>;
+  isAvailable(url: string): Promise<boolean>;
+  clearCache(pattern?: string): void;
+  getStats(): Record<string, any>;
+}
+
+export class WuSandbox {
+  create(appName: string, container: HTMLElement, options?: any): any;
+  cleanup(sandbox: any): void;
+}
+
+export class WuManifest {
+  load(appUrl: string): Promise<any>;
+  validate(manifest: any): any;
+  create(name: string, config?: any): any;
+  clearCache(pattern?: string): void;
+}
+
+export class WuApp {
+  mount(): Promise<void>;
+  unmount(): Promise<void>;
+}
+
+export class WuCache {
+  constructor(options?: { maxSize?: number; maxItems?: number; defaultTTL?: number; persistent?: boolean; storage?: string });
+  get(key: string): any;
+  set(key: string, value: any, ttl?: number): boolean;
+  delete(key: string): void;
+  clear(): void;
+  getStats(): Record<string, any>;
+}
+
+export class WuPerformance {
+  startMeasure(name: string, appName?: string): void;
+  endMeasure(name: string, appName?: string): number;
+  generateReport(): Record<string, any>;
+  getMetrics(appName: string): Record<string, any> | null;
+  getAllMetrics(): Record<string, any>;
+  clearMetrics(appName?: string): void;
+  configure(config: { enabled?: boolean; maxMeasurements?: number; devtoolsTimeline?: boolean; thresholds?: Record<string, number> }): void;
+
+  /** Read User Timing entries created by this framework. */
+  getDevToolsEntries(opts?: { type?: 'mark' | 'measure' | 'all'; appName?: string }): PerformanceEntry[];
+  /** Subscribe to wu:* User Timing entries via PerformanceObserver. */
+  observe(callback: (entry: PerformanceEntry) => void, opts?: { type?: 'mark' | 'measure' | 'all' }): () => void;
+}
+
+export class WuProxySandbox {
+  constructor(appName: string, options?: Record<string, any>);
+  activate(): any;
+  deactivate(): void;
+  patchWindow(): void;
+  unpatchWindow(): void;
+  setContainer(container: HTMLElement, shadowRoot: ShadowRoot): void;
+  getProxy(): any;
+  isActive(): boolean;
+  getStats(): Record<string, any>;
+}
+
+// WuSnapshotSandbox, WuHtmlParser, WuScriptExecutor, WuIframeSandbox, WuAI*,
+// and AI helpers are no longer exported from the main entry. Import via:
+//   import { WuIframeSandbox }    from 'wu-framework/sandbox/iframe';
+//   import { WuHtmlParser }       from 'wu-framework/sandbox/html-parser';
+//   import { WuScriptExecutor }   from 'wu-framework/sandbox/script-executor';
+//   import { WuAI, ... }          from 'wu-framework/ai';
+
+export class WuPluginSystem {
+  constructor(core: WuCore, options?: { hookTimeout?: number });
+  use(plugin: WuPlugin | ((options?: any) => WuPlugin), options?: any): void;
+  uninstall(pluginName: string): void;
+  getPlugin(pluginName: string): WuPlugin | undefined;
+  getStats(): Record<string, any>;
+  cleanup(): void;
+}
+
+export class WuLoadingStrategy {
+  constructor(core: WuCore);
+}
+
+export class WuPrefetch {
+  constructor(core: WuCore);
+  prefetch(appNames: string | string[], options?: any): Promise<void> | (() => void);
+  prefetchAll(options?: any): Promise<void> | (() => void);
+}
+
+export class WuOverrides {
+  constructor(config?: { enabled?: boolean; allowedDomains?: string[]; showIndicator?: boolean });
+  set(name: string, url: string, options?: { maxAge?: number; path?: string }): void;
+  remove(name: string): void;
+  getAll(): Record<string, string>;
+  clearAll(): void;
+  refresh(): void;
+  configure(config: { enabled?: boolean; allowedDomains?: string[]; showIndicator?: boolean }): void;
+  getStats(): Record<string, any>;
+  isEnabled(): boolean;
+  hasOverrides(): boolean;
+}
+
+export class WuErrorBoundary {
+  constructor(core: WuCore);
+  handle(error: Error, context?: any): Promise<{ recovered: boolean; action: string; message?: string }>;
+  register(handler: { name: string; canHandle: (error: Error) => boolean; handle: (error: Error, context: any) => Promise<any> }): void;
+  getErrorLog(limit?: number): any[];
+  getStats(): Record<string, any>;
+}
+
+export class WuLifecycleHooks {
+  constructor(core: WuCore);
+  use(phase: string, middleware: Function, options?: any): void;
+  execute(phase: string, context?: any): Promise<{ cancelled: boolean }>;
+}
+
+export class WuStyleBridge {
+  /** Returns an unsubscribe function. Multiple subscribers share one observer. */
+  observeStyleChanges(callback: () => void): () => void;
+  registerFullyIsolatedApp(appName: string, appUrl: string): void;
+  unregisterFullyIsolatedApp(appName: string): void;
+  injectStylesIntoShadow(shadowRoot: ShadowRoot, appName: string, styleMode?: string): Promise<number>;
+  cleanup(): void;
+}
+
+// --- Hook Factories ---
+
+export function createSimpleHook(fn: Function): any;
+export function createConditionalHook(condition: Function, fn: Function): any;
+export function createGuardHook(fn: Function): any;
+export function createTransformHook(fn: Function): any;
+export function createTimedHook(fn: Function, timeout: number): any;
+export function createPlugin(config: WuPlugin): WuPlugin;
+
+// --- Convenience API ---
+
+export const wu: WuCore;
+export default wu;
+
+export function init(apps: WuAppConfig[]): Promise<void>;
+export function mount(name: string, container: string): Promise<void>;
+export function unmount(name: string, opts?: any): Promise<void>;
+export function define(name: string, lifecycle: WuLifecycle): void;
+export function app(name: string, config: Partial<WuAppConfig>): WuApp;
+export function destroy(): Promise<void>;
+export function hide(name: string): Promise<void>;
+export function show(name: string): Promise<void>;
+export function isHidden(name: string): boolean;
+
+export function emit(event: string, data?: any, opts?: any): boolean;
+export function on(event: string, cb: (event: WuEvent) => void): () => void;
+export function once(event: string, cb: (event: WuEvent) => void): () => void;
+export function off(event: string, cb: (event: WuEvent) => void): void;
+
+export function getState(path?: string): any;
+export function setState(path: string, value: any): number;
+export function onStateChange(pattern: string, cb: (value: any) => void): () => void;
+export function syncStore(opts?: WuSyncOptions): WuSyncHandle;
+
+export function provide<T extends object>(name: string, impl: T, opts?: WuProvideOptions): WuCapabilityHandle;
+export function consume<T = any>(name: string, range?: string, opts?: { wait?: false; timeout?: number }): T;
+export function consume<T = any>(name: string, range: string, opts: { wait: true; timeout?: number }): Promise<T>;
+
+export function startMeasure(name: string, app?: string): void;
+export function endMeasure(name: string, app?: string): number;
+export function generatePerformanceReport(): Record<string, any>;
+
+export function prefetch(appNames: string | string[], opts?: any): Promise<void> | (() => void);
+export function prefetchAll(opts?: any): Promise<void> | (() => void);
+
+export function override(name: string, url: string, opts?: any): void;
+export function removeOverride(name: string): void;
+export function getOverrides(): Record<string, string>;
+export function clearOverrides(): void;
+
+export function usePlugin(plugin: WuPlugin | Function, opts?: any): void;
+export function useHook(phase: string, middleware: Function, opts?: any): void;
+
+export function silenceAllLogs(): void;
+export function enableAllLogs(): void;
+
+// --- Semver (capability-contract range matching, v2.5+) ---
+export function satisfies(version: string, range: string): boolean;
+export function parseVersion(v: string): [number, number, number];
+export function compareVersions(a: string | number[], b: string | number[]): number;
+
+/**
+ * Canonicalize styleMode aliases (v2.1+).
+ * - `'none'` → `'isolated'`
+ * - `'own-only'` → `'fully-isolated'`
+ * - Other inputs pass through unchanged.
+ */
+export function normalizeStyleMode(mode: string | undefined): string | undefined;
+
+/**
+ * DevTools bridge (v2.2+). A tiny always-present global so external inspectors
+ * and the built-in overlay can detect Wu and pull a full-page snapshot.
+ */
+export interface WuDevtoolsBridge {
+  version: string;
+  isWu: true;
+  inspect(opts?: { events?: number }): WuInspectSnapshot;
+  show(): Promise<{ close: () => void } | null>;
+  hide(): Promise<void>;
+  subscribe(cb: (event: WuEvent) => void): () => void;
+}
+
+declare global {
+  interface Window {
+    wu?: WuCore;
+    __WU_DEVTOOLS__?: WuDevtoolsBridge;
+  }
+}