@tooluminati/diagnostics 0.1.0

package/dist/index.js

@@ -0,0 +1,1141 @@
+// src/action-availability.ts
+function createActionAvailabilityTool(provider, name = "why_is_action_unavailable") {
+  return {
+    name,
+    description: "Explains whether a named UI action is available and returns validation, permission, or domain-rule blockers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: {
+          type: "string",
+          description: "Stable id of the action to inspect."
+        }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    validateArgs(args) {
+      if (typeof args !== "object" || args === null || typeof args.actionId !== "string") {
+        throw new Error("Expected { actionId: string }.");
+      }
+      return args;
+    },
+    execute: ({ actionId }) => provider.getActionAvailability(actionId) ?? {
+      actionId,
+      available: false,
+      reasons: ["Unknown action id."]
+    }
+  };
+}
+function createListActionsTool(provider, name = "list_available_actions") {
+  return {
+    name,
+    description: "Lists safe action availability summaries for the current page or app scope.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: () => ({ actions: provider.listActions?.() ?? [] })
+  };
+}
+
+// src/app-info.ts
+function createAppInfoTool(getInfo, name = "get_app_info") {
+  return {
+    name,
+    description: "Returns safe application metadata, environment, build, and Tooluminati status.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: () => getInfo()
+  };
+}
+function createVisibleToolsTool(name = "get_visible_agent_tools") {
+  return {
+    name,
+    description: "Returns visible WebMCP tools with safe metadata such as names, descriptions, annotations, and scope.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: (_args, context) => ({
+      tools: context.registry.getVisibleToolSummaries()
+    })
+  };
+}
+
+// src/errors.ts
+function isDevEnvironment() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+}
+var ClientErrorBuffer = class {
+  errors = [];
+  maxSize;
+  redact;
+  includeStacks;
+  getRoute;
+  constructor(options = 20) {
+    if (typeof options === "number") {
+      this.maxSize = options;
+      this.includeStacks = false;
+    } else {
+      this.maxSize = options.maxSize ?? 20;
+      if (options.redact) {
+        this.redact = options.redact;
+      }
+      this.includeStacks = options.includeStacks ?? false;
+      if (options.getRoute) {
+        this.getRoute = options.getRoute;
+      }
+    }
+  }
+  push(error) {
+    const route = error.route ?? this.getRoute?.();
+    const entry = {
+      message: error.message,
+      source: error.source,
+      timestamp: error.timestamp,
+      ...route ? { route } : {}
+    };
+    if (this.includeStacks && isDevEnvironment() && error.stack) {
+      entry.stack = error.stack;
+    }
+    const stored = this.redact?.(entry) ?? entry;
+    this.errors.unshift(stored);
+    this.errors.splice(this.maxSize);
+  }
+  list() {
+    return [...this.errors];
+  }
+  clear() {
+    this.errors.splice(0);
+  }
+};
+function createErrorCollector(options) {
+  if (options.enabled === false || typeof window === "undefined") {
+    return () => {
+    };
+  }
+  const onError = (event) => {
+    const stack = event.error instanceof Error ? event.error.stack : void 0;
+    options.buffer.push({
+      message: event.message,
+      source: event.filename ?? "window.onerror",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...stack ? { stack } : {}
+    });
+  };
+  const onRejection = (event) => {
+    const reason = event.reason;
+    const stack = reason instanceof Error ? reason.stack : void 0;
+    options.buffer.push({
+      message: reason instanceof Error ? reason.message : String(reason),
+      source: "unhandledrejection",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...stack ? { stack } : {}
+    });
+  };
+  window.addEventListener("error", onError);
+  window.addEventListener("unhandledrejection", onRejection);
+  return () => {
+    window.removeEventListener("error", onError);
+    window.removeEventListener("unhandledrejection", onRejection);
+  };
+}
+function createRecentClientErrorsTool(buffer, name = "get_recent_client_errors") {
+  return {
+    name,
+    description: "Returns recent redacted client-side errors captured by the app diagnostics buffer.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, untrustedContentHint: true },
+    execute: () => ({ errors: buffer.list() })
+  };
+}
+
+// src/feature-flags.ts
+function createFeatureFlagsTool(getFlags, name = "get_feature_flags_summary") {
+  return {
+    name,
+    description: "Returns safe feature flag names and enabled states without exposing user targeting data.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: () => ({ flags: getFlags() })
+  };
+}
+
+// src/hydration.ts
+function createHydrationHealthTracker() {
+  const health = { recoverableErrorCount: 0 };
+  return {
+    recordRecoverableError(error) {
+      health.recoverableErrorCount += 1;
+      health.lastRecoverableError = error instanceof Error ? error.message : String(error);
+    },
+    getHealth() {
+      return { ...health };
+    }
+  };
+}
+function createHydrationHealthTool(getHealth, name = "get_hydration_health") {
+  return {
+    name,
+    description: "Returns development-only React hydration health and recoverable error summary.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: () => getHealth()
+  };
+}
+
+// src/mounted-forms.ts
+function createMountedFormsRegistry() {
+  const forms = /* @__PURE__ */ new Map();
+  return {
+    register(summary) {
+      forms.set(summary.name, summary);
+      return () => {
+        forms.delete(summary.name);
+      };
+    },
+    unregister(name) {
+      forms.delete(name);
+    },
+    list() {
+      return [...forms.values()];
+    }
+  };
+}
+function createMountedFormsSummaryTool(registry, name = "get_mounted_forms_summary") {
+  return {
+    name,
+    description: "Returns summaries of mounted form diagnostics registered in the app.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: () => ({ forms: registry.list() })
+  };
+}
+
+// src/timeline.ts
+var DEFAULT_MAX_SIZE = 50;
+var DEFAULT_TOOL_LIMIT = 20;
+var VALID_CATEGORIES = /* @__PURE__ */ new Set([
+  "client_error",
+  "fetch_failure",
+  "route_change",
+  "action_blocked",
+  "tool_activated",
+  "tool_cancelled",
+  "agent_form_submit",
+  "toolchange",
+  "custom"
+]);
+var nextEventId = 0;
+function createEventId() {
+  nextEventId += 1;
+  return `tlm-${nextEventId}`;
+}
+function stripQuerySecrets(url) {
+  try {
+    const parsed = new URL(url, "http://local");
+    parsed.search = "";
+    return parsed.pathname + (parsed.hash || "");
+  } catch {
+    return url.split("?")[0] ?? url;
+  }
+}
+var TroubleshootingTimelineBuffer = class {
+  events = [];
+  maxSize;
+  redact;
+  constructor(options = {}) {
+    if (typeof options === "number") {
+      this.maxSize = options;
+    } else {
+      this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+      if (options.redact) {
+        this.redact = options.redact;
+      }
+    }
+  }
+  push(event) {
+    const stored = {
+      ...event,
+      id: event.id ?? createEventId(),
+      timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const finalEvent = this.redact?.(stored) ?? stored;
+    this.events.unshift(finalEvent);
+    this.events.splice(this.maxSize);
+    return finalEvent;
+  }
+  list(options) {
+    const limit = Math.max(
+      0,
+      Math.min(options?.limit ?? DEFAULT_TOOL_LIMIT, DEFAULT_TOOL_LIMIT)
+    );
+    let result = [...this.events];
+    if (options?.since) {
+      const sinceMs = Date.parse(options.since);
+      if (Number.isNaN(sinceMs)) {
+        return [];
+      }
+      result = result.filter((e) => Date.parse(e.timestamp) >= sinceMs);
+    }
+    if (options?.categories?.length) {
+      const cats = new Set(options.categories);
+      result = result.filter((e) => cats.has(e.category));
+    }
+    return result.slice(0, limit);
+  }
+  summary(events = this.events) {
+    const byCategory = {};
+    for (const event of events) {
+      byCategory[event.category] = (byCategory[event.category] ?? 0) + 1;
+    }
+    return { total: events.length, byCategory };
+  }
+  clear() {
+    this.events.splice(0);
+  }
+};
+var fetchTrackerCount = 0;
+var originalFetch;
+function createFetchFailureTracker(options) {
+  if (options.enabled === false || typeof window === "undefined") {
+    return () => {
+    };
+  }
+  if (fetchTrackerCount === 0) {
+    originalFetch = window.fetch.bind(window);
+  }
+  fetchTrackerCount += 1;
+  const baseFetch = originalFetch;
+  window.fetch = async (input, init) => {
+    const started = performance.now();
+    const method = (init?.method ?? "GET").toUpperCase();
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    if (options.ignoreUrls?.test(url)) {
+      return baseFetch(input, init);
+    }
+    try {
+      const response = await baseFetch(input, init);
+      if (!response.ok) {
+        const detail = options.redactBody === false ? `HTTP request failed before UI state updated.` : "HTTP request failed before UI state updated.";
+        options.buffer.push({
+          category: "fetch_failure",
+          title: `${method} ${stripQuerySecrets(url)} \u2014 ${response.status}`,
+          method,
+          url: stripQuerySecrets(url),
+          status: response.status,
+          durationMs: Math.round(performance.now() - started),
+          detail,
+          metadata: {
+            host: safeHost(url),
+            status: String(response.status)
+          }
+        });
+      }
+      return response;
+    } catch (error) {
+      options.buffer.push({
+        category: "fetch_failure",
+        title: `${method} ${stripQuerySecrets(url)} \u2014 network error`,
+        method,
+        url: stripQuerySecrets(url),
+        durationMs: Math.round(performance.now() - started),
+        detail: error instanceof Error ? error.message : "Network request failed.",
+        metadata: { host: safeHost(url) }
+      });
+      throw error;
+    }
+  };
+  return () => {
+    fetchTrackerCount = Math.max(0, fetchTrackerCount - 1);
+    if (fetchTrackerCount === 0 && originalFetch) {
+      window.fetch = originalFetch;
+      originalFetch = void 0;
+    }
+  };
+}
+function safeHost(url) {
+  try {
+    return new URL(url, window.location.origin).host;
+  } catch {
+    return "unknown";
+  }
+}
+function createTimelineFromErrorBuffer(buffer, timeline) {
+  const originalPush = buffer.push.bind(buffer);
+  buffer.push = (error) => {
+    originalPush(error);
+    timeline.push({
+      category: "client_error",
+      title: error.message,
+      message: error.message,
+      source: error.source,
+      detail: "Client error captured by diagnostics buffer.",
+      metadata: {
+        source: error.source,
+        ...error.route ? { route: error.route } : {}
+      },
+      untrusted: true
+    });
+  };
+  return () => {
+    buffer.push = originalPush;
+  };
+}
+function createWebMcpLifecycleCollector(options) {
+  if (options.enabled === false || typeof window === "undefined") {
+    return () => {
+    };
+  }
+  const cleanups = [];
+  const onToolActivated = (event) => {
+    const detail = event.detail;
+    options.buffer.push({
+      category: "tool_activated",
+      title: `agent activated ${detail?.toolName ?? "form tool"}`,
+      toolName: detail?.toolName,
+      formId: detail?.form?.id,
+      detail: "Declarative form tool activated by the agent."
+    });
+  };
+  const onToolCancel = (event) => {
+    const detail = event.detail;
+    options.buffer.push({
+      category: "tool_cancelled",
+      title: `agent cancelled ${detail?.toolName ?? "form tool"}`,
+      toolName: detail?.toolName,
+      detail: "Agent cancelled a declarative form tool."
+    });
+  };
+  const onAgentFormSubmit = (event) => {
+    const submitEvent = event;
+    if (!submitEvent.agentInvoked) {
+      return;
+    }
+    const form = event.target;
+    const toolName = form?.getAttribute("toolname") ?? "form";
+    options.buffer.push({
+      category: "agent_form_submit",
+      title: `agent submitted ${toolName}`,
+      toolName,
+      formId: form?.id,
+      detail: "Agent invoked declarative form submit."
+    });
+  };
+  const onToolChange = () => {
+    options.buffer.push({
+      category: "toolchange",
+      title: "tool registry changed",
+      added: [],
+      removed: [],
+      detail: "WebMCP tool registry changed on document.modelContext."
+    });
+  };
+  window.addEventListener("toolactivated", onToolActivated);
+  window.addEventListener("toolcancel", onToolCancel);
+  window.addEventListener("submit", onAgentFormSubmit, true);
+  cleanups.push(() => {
+    window.removeEventListener("toolactivated", onToolActivated);
+    window.removeEventListener("toolcancel", onToolCancel);
+    window.removeEventListener("submit", onAgentFormSubmit, true);
+  });
+  const modelContext = document.modelContext;
+  if (modelContext?.addEventListener) {
+    modelContext.addEventListener("toolchange", onToolChange);
+    cleanups.push(() => {
+      modelContext.removeEventListener("toolchange", onToolChange);
+    });
+  }
+  return () => {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+  };
+}
+function createTroubleshootingTimelineTool(buffer, name = "get_troubleshooting_timeline") {
+  return {
+    name,
+    description: "Returns a bounded, redacted timeline of recent runtime incidents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        categories: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional event categories to include."
+        },
+        since: {
+          type: "string",
+          description: "ISO timestamp; only events after this time."
+        },
+        limit: {
+          type: "integer",
+          maximum: DEFAULT_TOOL_LIMIT,
+          description: "Max events to return (cap 20)."
+        }
+      },
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, untrustedContentHint: true },
+    validateArgs(args) {
+      if (typeof args !== "object" || args === null) {
+        return {};
+      }
+      const input = args;
+      if (input.categories?.length) {
+        const invalid = input.categories.filter(
+          (category) => !VALID_CATEGORIES.has(category)
+        );
+        if (invalid.length) {
+          throw new Error(`Unknown timeline categories: ${invalid.join(", ")}`);
+        }
+      }
+      if (input.limit !== void 0 && input.limit < 0) {
+        throw new Error("limit must be >= 0.");
+      }
+      return input;
+    },
+    execute: (input) => {
+      const events = buffer.list({
+        ...input.categories?.length ? {
+          categories: input.categories
+        } : {},
+        ...input.since ? { since: input.since } : {},
+        ...input.limit !== void 0 ? { limit: input.limit } : {}
+      });
+      return {
+        events,
+        summary: buffer.summary(events)
+      };
+    }
+  };
+}
+
+// src/webmcp-environment.ts
+import {
+  getModelContext,
+  isWebMcpSupported
+} from "@tooluminati/core";
+function createWebMcpEnvironmentSummary(options = {}) {
+  const globalObject = options.globalObject ?? globalThis;
+  let usingNavigatorFallback = false;
+  const documentContext = typeof globalObject.document !== "undefined" ? globalObject.document.modelContext : void 0;
+  getModelContext({
+    globalObject,
+    onNavigatorFallback: () => {
+      usingNavigatorFallback = true;
+    }
+  });
+  const supported = isWebMcpSupported({ globalObject });
+  const origin = typeof globalObject.location !== "undefined" ? globalObject.location.origin : "unknown";
+  const toolCount = options.registry?.getRegisteredToolNames().length ?? 0;
+  const checks = [];
+  const warnings = [];
+  checks.push({
+    id: "document.modelContext",
+    label: "document.modelContext",
+    value: documentContext ? "available" : "missing",
+    status: documentContext ? "ok" : "fail",
+    ...documentContext ? {} : {
+      hint: "No document.modelContext on this page. Enable WebMCP in Chrome or attach the Model Context Inspector Extension."
+    }
+  });
+  checks.push({
+    id: "navigator.modelContext",
+    label: "navigator.modelContext fallback",
+    value: usingNavigatorFallback ? "in use" : "not used",
+    status: usingNavigatorFallback ? "warn" : "ok",
+    ...usingNavigatorFallback ? {
+      hint: "Deprecated navigator.modelContext path detected. Migrate to document.modelContext."
+    } : {}
+  });
+  const originIsolation = detectOriginIsolationIssue(globalObject);
+  checks.push({
+    id: "origin-isolation",
+    label: "Origin isolation",
+    value: originIsolation.value,
+    status: originIsolation.status,
+    ...originIsolation.hint ? { hint: originIsolation.hint } : {}
+  });
+  if (originIsolation.warning) {
+    warnings.push(originIsolation.warning);
+  }
+  const permissionsPolicy = detectPermissionsPolicy(globalObject);
+  checks.push({
+    id: "permissions-policy",
+    label: "tools Permissions-Policy",
+    value: permissionsPolicy.value,
+    status: permissionsPolicy.status,
+    ...permissionsPolicy.hint ? { hint: permissionsPolicy.hint } : {}
+  });
+  if (permissionsPolicy.warning) {
+    warnings.push(permissionsPolicy.warning);
+  }
+  if (toolCount === 0 && supported) {
+    warnings.push("No tools registered yet.");
+    checks.push({
+      id: "tool-count",
+      label: "Registered tools",
+      value: "0",
+      status: "warn",
+      hint: "WebMCP is supported but no tools are registered. Verify the Tooluminati provider is mounted."
+    });
+  }
+  if (!supported) {
+    warnings.push("WebMCP is unsupported in this browser context.");
+  }
+  return {
+    supported,
+    toolCount,
+    origin,
+    usingNavigatorFallback,
+    checks,
+    warnings
+  };
+}
+function detectOriginIsolationIssue(globalObject) {
+  if (typeof globalObject.document === "undefined") {
+    return { value: "n/a", status: "muted" };
+  }
+  const doc = globalObject.document;
+  if (doc.domain && doc.domain.length > 0) {
+    const hint = "document.domain is set. Origin-Agent-Cluster may be ?0. Remove document.domain writes or set Origin-Agent-Cluster: ?1.";
+    return {
+      value: "review",
+      status: "warn",
+      hint,
+      warning: hint
+    };
+  }
+  return { value: "ok", status: "ok" };
+}
+function detectPermissionsPolicy(globalObject) {
+  if (typeof globalObject.document === "undefined") {
+    return { value: "n/a", status: "muted" };
+  }
+  const doc = globalObject.document;
+  if (doc.permissionsPolicy?.allowsFeature) {
+    const allowed = doc.permissionsPolicy.allowsFeature("tools");
+    if (!allowed) {
+      const hint = "tools is blocked by Permissions-Policy. Allow tools for this origin or review iframe allow attributes.";
+      return {
+        value: "blocked",
+        status: "fail",
+        hint,
+        warning: hint
+      };
+    }
+  }
+  if (typeof globalObject.document.querySelector !== "function") {
+    return { value: "self", status: "ok" };
+  }
+  const iframe = globalObject.document.querySelector("iframe");
+  if (iframe && iframe.src && !iframe.src.startsWith(globalObject.location.origin)) {
+    const hint = "Cross-origin iframe detected. Verify Permissions-Policy allows tools for embedded origins.";
+    return {
+      value: "review cross-origin iframe",
+      status: "warn",
+      hint,
+      warning: hint
+    };
+  }
+  return { value: "self", status: "ok" };
+}
+function createWebMcpEnvironmentTool(getSummary, name = "get_webmcp_environment") {
+  return {
+    name,
+    description: "Reports WebMCP browser support, registered tool count, and setup warnings.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    execute: () => getSummary()
+  };
+}
+
+// src/workflow-blockers.ts
+function createWorkflowBlockersTool(sources, name = "get_workflow_blockers") {
+  return {
+    name,
+    description: "Aggregates action, form, query, and error blockers for the current workflow.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true, untrustedContentHint: true },
+    execute: () => {
+      const actions = sources.actionProvider?.listActions?.().map((action) => ({
+        actionId: action.actionId,
+        available: action.available,
+        reasons: action.available ? [] : action.reasons
+      })) ?? [];
+      const result = {
+        actions,
+        forms: sources.formSummaries?.() ?? [],
+        declarativeForms: sources.declarativeFormSummaries?.() ?? [],
+        queries: sources.querySummaries?.() ?? [],
+        errors: sources.recentErrors?.() ?? []
+      };
+      const hydration = sources.hydrationHealth?.();
+      if (hydration) {
+        result.hydration = hydration;
+      }
+      const flags = sources.featureFlags?.();
+      if (flags) {
+        result.featureFlags = flags;
+      }
+      return result;
+    }
+  };
+}
+function formSummaryFromMounted(form) {
+  const blockers = form.errors.map((e) => `${e.path}: ${e.message}`);
+  if (form.submitting) {
+    blockers.push("Form is submitting.");
+  }
+  return {
+    name: form.name,
+    valid: blockers.length === 0,
+    submitting: form.submitting,
+    blockers
+  };
+}
+function discoverDeclarativeForms(root = typeof document !== "undefined" ? document : null) {
+  if (!root) {
+    return [];
+  }
+  const summaries = /* @__PURE__ */ new Map();
+  for (const form of root.querySelectorAll("form[toolname]")) {
+    const el = form;
+    summaries.set(el.getAttribute("toolname") ?? "unknown", {
+      toolName: el.getAttribute("toolname") ?? "unknown",
+      ...el.id ? { formId: el.id } : {},
+      autoSubmit: el.hasAttribute("toolautosubmit")
+    });
+  }
+  return [...summaries.values()];
+}
+
+// src/troubleshooting-guidance.ts
+var TROUBLESHOOTING_GUIDANCE = {
+  "document.modelContext": {
+    title: "WebMCP host missing",
+    hint: "No document.modelContext on this page. Enable WebMCP in Chrome or attach the Model Context Inspector Extension. Tools cannot register until this resolves.",
+    severity: "error"
+  },
+  "navigator.modelContext": {
+    title: "Deprecated fallback in use",
+    hint: "Migrate from navigator.modelContext to document.modelContext. The fallback is not a supported long-term surface.",
+    severity: "warn"
+  },
+  "origin-isolation": {
+    title: "Origin isolation review",
+    hint: "Origin-Agent-Cluster may be ?0 when document.domain is set. Remove document.domain writes or set Origin-Agent-Cluster: ?1.",
+    severity: "warn"
+  },
+  "permissions-policy": {
+    title: "Permissions-Policy review",
+    hint: "Cross-origin iframes may block tools unless Permissions-Policy allows the tools feature for this origin.",
+    severity: "warn"
+  },
+  "tool-count": {
+    title: "No tools registered",
+    hint: "Verify WebMcpProvider or provideWebMcpRegistry is mounted and tools are registered in the current route scope.",
+    severity: "warn"
+  },
+  "output-budget": {
+    title: "Tool output budget exceeded",
+    hint: "A tool emitted more than the recommended ~1.5K chars. Trim fields or enable redaction to stay within Chrome guidance.",
+    severity: "warn"
+  },
+  fetch_failure: {
+    title: "Fetch failure",
+    hint: "Inspect get_troubleshooting_timeline and get_workflow_blockers for structured HTTP failure context.",
+    severity: "error"
+  },
+  client_error: {
+    title: "Client error",
+    hint: "See get_recent_client_errors and the timeline client_error entries for redacted stack traces in dev.",
+    severity: "error"
+  },
+  action_blocked: {
+    title: "Action blocked",
+    hint: "Call why_is_action_unavailable or get_workflow_blockers for reasons beyond disabled=true in the DOM.",
+    severity: "warn"
+  },
+  toolchange: {
+    title: "Tool registry changed",
+    hint: "Tools were added or removed. Check route mounts and scoped providers if the count is unexpected.",
+    severity: "info"
+  },
+  WebMcpUnavailable: {
+    title: "WebMCP unavailable",
+    hint: "Tooluminati could not find document.modelContext. Registration was deferred until a host becomes available.",
+    severity: "error"
+  },
+  TypeError: {
+    title: "Runtime TypeError",
+    hint: "Check component props and optional chaining. Errors are captured by WebMcpErrorBoundary when enabled.",
+    severity: "error"
+  },
+  NetworkError: {
+    title: "Network failure",
+    hint: "Verify API availability and CORS. Timeline fetch_failure entries include status and timing.",
+    severity: "error"
+  }
+};
+function getGuidanceForEnvironmentCheck(check) {
+  if (check.hint) {
+    return {
+      title: check.label,
+      hint: check.hint,
+      severity: check.status === "fail" ? "error" : check.status === "warn" ? "warn" : "info"
+    };
+  }
+  return TROUBLESHOOTING_GUIDANCE[check.id];
+}
+function getGuidanceForTimelineEvent(event) {
+  const base = TROUBLESHOOTING_GUIDANCE[event.category];
+  if (base) {
+    return {
+      ...base,
+      hint: event.detail ? `${base.hint} ${event.detail}` : base.hint
+    };
+  }
+  return void 0;
+}
+function getGuidanceForClientError(error) {
+  for (const key of ["WebMcpUnavailable", "TypeError", "NetworkError"]) {
+    if (error.message.includes(key)) {
+      return TROUBLESHOOTING_GUIDANCE[key];
+    }
+  }
+  return TROUBLESHOOTING_GUIDANCE.client_error;
+}
+function timelineEventGroup(category) {
+  if (category === "fetch_failure" || category === "client_error") {
+    return "failures";
+  }
+  if (category === "action_blocked") {
+    return "blocked";
+  }
+  if (category === "tool_activated" || category === "tool_cancelled" || category === "toolchange") {
+    return "tools";
+  }
+  if (category === "route_change" || category === "agent_form_submit") {
+    return "nav";
+  }
+  return "all";
+}
+
+// src/troubleshooting-panel.ts
+var STORAGE_KEY = "tooluminati.troubleshootingPanel.collapsed";
+function relativeTime(iso) {
+  const delta = Date.now() - Date.parse(iso);
+  if (Number.isNaN(delta) || delta < 0) {
+    return "now";
+  }
+  const seconds = Math.round(delta / 1e3);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.round(seconds / 60);
+  return `${minutes}m`;
+}
+function dedupeErrors(errors) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const error of errors) {
+    counts.set(error.message, (counts.get(error.message) ?? 0) + 1);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const views = [];
+  for (const error of errors) {
+    if (seen.has(error.message)) {
+      continue;
+    }
+    seen.add(error.message);
+    const guidance = getGuidanceForClientError(error)?.hint;
+    views.push({
+      id: error.message,
+      message: error.message,
+      source: error.source,
+      time: relativeTime(error.timestamp),
+      count: counts.get(error.message) ?? 1,
+      ...error.stack ? { stack: error.stack } : {},
+      ...guidance ? { guidance } : {}
+    });
+  }
+  return views;
+}
+function computeTroubleshootingPanelState(snapshot) {
+  if (!snapshot.supported) {
+    return "unsupported";
+  }
+  const hasIncidents = snapshot.issueCount > 0 || snapshot.errors.length > 0 || snapshot.events.some(
+    (event) => event.group === "failures" || event.group === "blocked" || event.category === "toolchange"
+  );
+  if (!hasIncidents && snapshot.events.length === 0 && snapshot.errors.length === 0) {
+    return snapshot.toolCount === 0 ? "empty" : "ok";
+  }
+  if (hasIncidents) {
+    return "attention";
+  }
+  return "ok";
+}
+function serializeTroubleshootingDiagnostics(snapshot) {
+  return JSON.stringify(
+    {
+      webmcp: {
+        supported: snapshot.supported,
+        toolCount: snapshot.toolCount,
+        origin: snapshot.origin,
+        panelState: snapshot.panelState
+      },
+      checks: snapshot.checks.map((c) => ({
+        label: c.label,
+        value: c.value,
+        status: c.status,
+        ...c.guidance ? { guidance: c.guidance } : {}
+      })),
+      timeline: snapshot.events.map((e) => ({
+        category: e.category,
+        title: e.title,
+        t: e.time,
+        ...e.guidance ? { guidance: e.guidance } : {},
+        ...e.metadata ? { metadata: e.metadata } : {}
+      })),
+      clientErrors: snapshot.errors.map((e) => ({
+        message: e.message,
+        count: e.count,
+        ...e.guidance ? { guidance: e.guidance } : {}
+      })),
+      warnings: snapshot.warnings
+    },
+    null,
+    2
+  );
+}
+function buildTroubleshootingPanelSnapshot(sources, options = {}) {
+  const env = sources.environment() ?? createWebMcpEnvironmentSummary({
+    ...sources.registry ? { registry: sources.registry } : {},
+    ...options.registry ? { registry: options.registry } : {}
+  });
+  const eventLimit = options.eventLimit ?? 20;
+  const rawEvents = sources.timeline.list({ limit: eventLimit });
+  const events = rawEvents.map((event) => {
+    const guidance = getGuidanceForTimelineEvent(event)?.hint;
+    return {
+      id: event.id,
+      category: event.category,
+      group: timelineEventGroup(event.category),
+      title: event.title,
+      time: relativeTime(event.timestamp),
+      ...event.detail ? { detail: event.detail } : {},
+      ...event.metadata ? { metadata: event.metadata } : {},
+      ...guidance ? { guidance } : {}
+    };
+  });
+  const checks = env.checks.map((check) => {
+    const guidance = getGuidanceForEnvironmentCheck(check)?.hint;
+    return {
+      ...check,
+      ...guidance ? { guidance } : {}
+    };
+  });
+  const errors = dedupeErrors(sources.errors.list());
+  const warnCount = checks.filter(
+    (c) => c.status === "warn" || c.status === "fail"
+  ).length;
+  const incidentEvents = events.filter(
+    (event) => event.group === "failures" || event.group === "blocked"
+  ).length;
+  const issueCount = warnCount + errors.length + incidentEvents;
+  const snapshot = {
+    supported: env.supported,
+    toolCount: env.toolCount,
+    origin: env.origin,
+    issueCount,
+    checks,
+    events,
+    errors,
+    warnings: env.warnings,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    panelState: "ok"
+  };
+  snapshot.panelState = computeTroubleshootingPanelState(snapshot);
+  return snapshot;
+}
+function createTroubleshootingPanelViewModel(sources, options = {}) {
+  const listeners = /* @__PURE__ */ new Set();
+  let timer;
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  if (options.pollMs && options.pollMs > 0) {
+    timer = setInterval(notify, options.pollMs);
+  }
+  return {
+    refresh() {
+      return buildTroubleshootingPanelSnapshot(sources, options);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      listeners.clear();
+      if (timer) {
+        clearInterval(timer);
+      }
+    }
+  };
+}
+function createTroubleshootingPanelVisibilityController(options) {
+  const storageKey = options?.storageKey ?? STORAGE_KEY;
+  const listeners = /* @__PURE__ */ new Set();
+  let visible = true;
+  let collapsed = options?.startCollapsed ?? readCollapsed(storageKey);
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  return {
+    get visible() {
+      return visible;
+    },
+    get collapsed() {
+      return collapsed;
+    },
+    show() {
+      visible = true;
+      notify();
+    },
+    hide() {
+      visible = false;
+      notify();
+    },
+    toggle() {
+      visible = !visible;
+      notify();
+    },
+    setCollapsed(next) {
+      collapsed = next;
+      writeCollapsed(storageKey, next);
+      notify();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+function isPanelEnabledByDefault(enabled) {
+  if (enabled === true) {
+    return true;
+  }
+  if (enabled === false) {
+    return false;
+  }
+  const nodeEnv = typeof process !== "undefined" ? process.env?.NODE_ENV : void 0;
+  if (!nodeEnv || nodeEnv === "development" || nodeEnv === "test") {
+    return true;
+  }
+  return nodeEnv !== "production";
+}
+function isPanelUrlOverrideEnabled(allowUrlOverride) {
+  if (!allowUrlOverride || typeof window === "undefined") {
+    return false;
+  }
+  return new URLSearchParams(window.location.search).has("tooluminati-panel");
+}
+function readCollapsed(storageKey) {
+  if (typeof sessionStorage === "undefined") {
+    return false;
+  }
+  return sessionStorage.getItem(storageKey) === "1";
+}
+function writeCollapsed(storageKey, collapsed) {
+  if (typeof sessionStorage === "undefined") {
+    return;
+  }
+  sessionStorage.setItem(storageKey, collapsed ? "1" : "0");
+}
+function filterPanelEvents(events, filter) {
+  if (filter === "all") {
+    return events;
+  }
+  return events.filter((event) => event.group === filter);
+}
+export {
+  ClientErrorBuffer,
+  TROUBLESHOOTING_GUIDANCE,
+  TroubleshootingTimelineBuffer,
+  buildTroubleshootingPanelSnapshot,
+  computeTroubleshootingPanelState,
+  createActionAvailabilityTool,
+  createAppInfoTool,
+  createErrorCollector,
+  createFeatureFlagsTool,
+  createFetchFailureTracker,
+  createHydrationHealthTool,
+  createHydrationHealthTracker,
+  createListActionsTool,
+  createMountedFormsRegistry,
+  createMountedFormsSummaryTool,
+  createRecentClientErrorsTool,
+  createTimelineFromErrorBuffer,
+  createTroubleshootingPanelViewModel,
+  createTroubleshootingPanelVisibilityController,
+  createTroubleshootingTimelineTool,
+  createVisibleToolsTool,
+  createWebMcpEnvironmentSummary,
+  createWebMcpEnvironmentTool,
+  createWebMcpLifecycleCollector,
+  createWorkflowBlockersTool,
+  discoverDeclarativeForms,
+  filterPanelEvents,
+  formSummaryFromMounted,
+  getGuidanceForClientError,
+  getGuidanceForEnvironmentCheck,
+  getGuidanceForTimelineEvent,
+  isPanelEnabledByDefault,
+  isPanelUrlOverrideEnabled,
+  serializeTroubleshootingDiagnostics,
+  timelineEventGroup
+};