@apiboost/omnispec 1.1.0-next.2 → 1.1.0-next.4

package/dist/esm/chunks/{AsyncApiSpec-BzhfaQ_T.js → AsyncApiSpec-C0tdvyEP.js}

@@ -2,7 +2,7 @@ import { jsxs, jsx, Fragment as Fragment$1 } from 'react/jsx-runtime';
 import { useCallback, Fragment, useState, useMemo } from 'react';
 import { cx, css } from '@emotion/css';
 import { a as useSpecFetcher, I as Icon, m as mq, r as resolveSchemaStyle, S as SpecType, T as ThemeProvider, L as LoadingScreen, b as SpecStatusScreen, E as ErrorMessage, N as NavTree, h as buildSidebar, C as ConfigProvider, e as DocLayout } from './useSpecFetcher-BvVfMuzf.js';
-import { M as MarkdownRenderer, C as CodeBlock, T as Tabs, t as SchemaTree, A as schemaToNodes, x as generateExample, J as ExampleSelector, d as ExpandableCard, f as MethodBar, K as buildConstraints, S as SchemaBadge, R as ReferenceLayout, a as Collapsible, D as useHashScroll, y as requestExpand, w as flattenNavItemIds, G as useScrollSpy, u as SearchBar, L as ExpandProvider, v as SpecToolbar, z as resolveDownloadLink } from './Collapsible-MyJB2agz.js';
+import { M as MarkdownRenderer, T as Tabs, C as CodeBlock, t as SchemaTree, A as schemaToNodes, x as generateExample, J as ExampleSelector, d as ExpandableCard, f as MethodBar, K as buildConstraints, S as SchemaBadge, R as ReferenceLayout, a as Collapsible, D as useHashScroll, y as requestExpand, w as flattenNavItemIds, G as useScrollSpy, u as SearchBar, L as ExpandProvider, v as SpecToolbar, z as resolveDownloadLink } from './Collapsible-CPxS90KX.js';
 import { E as ErrorBoundary } from './ErrorBoundary-9pDlZFfM.js';
 import { r as resolveRefs, p as parse, d as decodeJsonPointerSegment } from './ref-resolver-B0C36NuQ.js';
 import '@emotion/styled';
@@ -39,6 +39,16 @@ function mergeMessageLayer(base, override) {
   }
   return result;
 }
+function deriveAppliedTraitNames(traits, rawTraits) {
+  return traits.map((trait, i) => {
+    const raw = rawTraits?.[i];
+    if (raw && typeof raw === "object" && typeof raw.$ref === "string") {
+      const last = raw.$ref.split("/").pop();
+      if (last) return decodeJsonPointerSegment(last);
+    }
+    return trait.name ?? trait.title ?? `trait ${i + 1}`;
+  });
+}
 function applyMessageTraits(msg, isV3) {
   if (!msg.traits || msg.traits.length === 0) return msg;
   if (isV3) {
@@ -82,7 +92,7 @@ async function parseAsyncApiSpec(specInput) {
   const rawApi = raw;
   const defaultContentType = api.defaultContentType;
   const channels = isV3 ? extractChannelsV3(api, rawApi, defaultContentType) : extractChannelsV2(api, defaultContentType);
-  const components = extractComponents(api, isV3, defaultContentType);
+  const components = extractComponents(api, rawApi, isV3, defaultContentType);
   const root = api;
   const tags = api.tags?.map((tag) => {
     const raw2 = tag;
@@ -197,11 +207,20 @@ function resolveChannelName(rawChannel, resolvedChannel, addressToName) {
   }
   return void 0;
 }
+function normalizeReplyAddress(address) {
+  if (typeof address === "string") {
+    return address.length > 0 ? { value: address } : void 0;
+  }
+  if (address && typeof address === "object") {
+    const { location, description } = address;
+    if (location || description) return { location, description };
+  }
+  return void 0;
+}
 function extractChannelsV3(api, rawApi, defaultContentType) {
-  if (!api.channels) return [];
   const channelMap = /* @__PURE__ */ new Map();
   const addressToName = /* @__PURE__ */ new Map();
-  for (const [channelName, ch] of Object.entries(api.channels)) {
+  for (const [channelName, ch] of Object.entries(api.channels ?? {})) {
     const raw = ch;
     const address = ch.address ?? channelName;
     addressToName.set(address, channelName);
@@ -245,9 +264,10 @@ function extractChannelsV3(api, rawApi, defaultContentType) {
         addressToName
       );
       const raw = op;
-      const reply = replyMessages.length > 0 || op.reply?.address || replyChannelName ? {
+      const replyAddress = normalizeReplyAddress(op.reply?.address);
+      const reply = replyMessages.length > 0 || replyAddress || replyChannelName ? {
         messages: replyMessages,
-        address: op.reply?.address,
+        address: replyAddress,
         channelName: replyChannelName
       } : void 0;
       const operation = {
@@ -281,16 +301,17 @@ function extractChannelsV3(api, rawApi, defaultContentType) {
     channels.push({
       name: "__unassigned__",
       address: "Unassigned operations",
-      description: "These operations reference a channel that is not defined in this document.",
+      description: "Unresolved reference: these operations reference an undefined channel (the channel is missing from this document, or the document defines no channels). They are surfaced here rather than dropped.",
       operations: orphanOperations
     });
   }
   return channels;
 }
-function convertMessage(rawMsg, isV3, defaultContentType) {
+function convertMessage(rawMsg, isV3, defaultContentType, rawTraits) {
   const msg = applyMessageTraits(rawMsg, isV3);
   const hasOwnContentType = typeof msg.contentType === "string" && msg.contentType.length > 0;
   const contentType = hasOwnContentType ? msg.contentType : defaultContentType ?? "application/json";
+  const appliedTraits = rawMsg.traits && rawMsg.traits.length > 0 ? deriveAppliedTraitNames(rawMsg.traits, rawTraits) : void 0;
   return {
     name: msg.name,
     title: msg.title,
@@ -305,15 +326,17 @@ function convertMessage(rawMsg, isV3, defaultContentType) {
     tags: msg.tags,
     examples: msg.examples,
     bindings: msg.bindings,
-    externalDocs: msg.externalDocs
+    externalDocs: msg.externalDocs,
+    appliedTraits
   };
 }
-function extractComponents(api, isV3, defaultContentType) {
+function extractComponents(api, rawApi, isV3, defaultContentType) {
   const components = api.components;
   const rawMessages = api.components?.messages ?? {};
+  const rawComponentMessages = rawApi.components?.messages ?? {};
   const messages = {};
   for (const [name, msg] of Object.entries(rawMessages)) {
-    messages[name] = convertMessage(msg, isV3, defaultContentType);
+    messages[name] = convertMessage(msg, isV3, defaultContentType, rawComponentMessages[name]?.traits);
   }
   return {
     schemas: api.components?.schemas ?? {},
@@ -394,19 +417,17 @@ function useAsyncApiSpec(spec) {
   return useSpecFetcher(spec, parser);
 }
 
-function ExternalDocsLink({ externalDocs, context, className }) {
-  const label = externalDocs.description ?? "External docs";
-  const ariaLabel = `${context ? `${context} external docs` : "External docs"}, opens in new tab`;
+function ExternalLink({ href, children, label, className }) {
   return /* @__PURE__ */ jsxs(
     "a",
     {
-      href: externalDocs.url,
+      href,
       target: "_blank",
       rel: "noopener noreferrer",
-      "aria-label": ariaLabel,
+      "aria-label": `${label}, opens in new tab`,
       className: cx(linkStyle$1, className),
       children: [
-        label,
+        children,
         /* @__PURE__ */ jsx(Icon, { name: "external-link", size: "0.875em" })
       ]
     }
@@ -416,7 +437,6 @@ const linkStyle$1 = css({
   display: "inline-flex",
   alignItems: "center",
   gap: "0.25rem",
-  fontSize: "var(--omnispec-font-size-xs)",
   color: "var(--omnispec-fg-link)",
   textDecoration: "none",
   minWidth: 0,
@@ -426,6 +446,15 @@ const linkStyle$1 = css({
   }
 });
 
+function ExternalDocsLink({ externalDocs, context, className }) {
+  const label = externalDocs.description ?? "External docs";
+  const ariaLabel = context ? `${context} external docs` : "External docs";
+  return /* @__PURE__ */ jsx(ExternalLink, { href: externalDocs.url, label: ariaLabel, className: cx(docsLinkStyle, className), children: label });
+}
+const docsLinkStyle = css({
+  fontSize: "var(--omnispec-font-size-xs)"
+});
+
 const containerStyle$4 = css({
   marginBottom: "2rem",
   paddingBottom: "1.5rem",
@@ -489,12 +518,19 @@ function AsyncOverview({ spec }) {
       ] }),
       spec.contact.url && /* @__PURE__ */ jsxs("span", { children: [
         " \xB7 ",
-        /* @__PURE__ */ jsx("a", { href: spec.contact.url, target: "_blank", rel: "noopener noreferrer", className: linkStyle, children: spec.contact.url })
+        /* @__PURE__ */ jsx(
+          ExternalLink,
+          {
+            href: spec.contact.url,
+            label: `${spec.contact.name ?? spec.title ?? "Contact"} website`,
+            children: spec.contact.url
+          }
+        )
       ] })
     ] }),
     spec.license && /* @__PURE__ */ jsxs("div", { className: metaStyle, children: [
       "License: ",
-      spec.license.url ? /* @__PURE__ */ jsx("a", { href: spec.license.url, target: "_blank", rel: "noopener noreferrer", className: linkStyle, children: spec.license.name }) : spec.license.name
+      spec.license.url ? /* @__PURE__ */ jsx(ExternalLink, { href: spec.license.url, label: `${spec.license.name} license`, children: spec.license.name }) : spec.license.name
     ] }),
     spec.externalDocs && /* @__PURE__ */ jsx("div", { className: metaStyle, children: /* @__PURE__ */ jsx(ExternalDocsLink, { externalDocs: spec.externalDocs, context: spec.title ?? "API" }) })
   ] });
@@ -574,7 +610,7 @@ function isScalarArray(value) {
     (item) => item === null || typeof item !== "object"
   );
 }
-function renderValue(value) {
+function renderValue(value, verbatim) {
   if (value === null) return /* @__PURE__ */ jsx("span", { className: mutedStyle, children: "null" });
   if (typeof value === "boolean") return /* @__PURE__ */ jsx("code", { className: codeStyle, children: value ? "true" : "false" });
   if (typeof value === "number") return /* @__PURE__ */ jsx("code", { className: codeStyle, children: String(value) });
@@ -592,7 +628,7 @@ function renderValue(value) {
     }
     const nested = Object.entries(value).filter(([, v]) => v !== void 0);
     if (nested.length === 0) return /* @__PURE__ */ jsx("span", { className: mutedStyle, children: "none" });
-    return /* @__PURE__ */ jsx("div", { className: nestedStyle, children: /* @__PURE__ */ jsx(FieldRows, { fields: nested }) });
+    return /* @__PURE__ */ jsx("div", { className: nestedStyle, children: /* @__PURE__ */ jsx(FieldRows, { fields: nested, verbatim }) });
   }
   return /* @__PURE__ */ jsx("code", { className: jsonStyle, children: JSON.stringify(value) });
 }
@@ -620,6 +656,9 @@ function SchemaLeaf({ schema }) {
   const type = typeof schema.type === "string" ? schema.type : void 0;
   const description = typeof schema.description === "string" ? schema.description : void 0;
   const enumValues = Array.isArray(schema.enum) ? schema.enum : void 0;
+  if (enumValues && enumValues.length === 1 && !description) {
+    return /* @__PURE__ */ jsx("div", { className: schemaLeafStyle, children: /* @__PURE__ */ jsx("code", { className: enumItemStyle, children: String(enumValues[0]) }) });
+  }
   return /* @__PURE__ */ jsxs("div", { className: schemaLeafStyle, children: [
     type && /* @__PURE__ */ jsx("span", { className: schemaTypeStyle, children: type }),
     description && /* @__PURE__ */ jsx("span", { className: schemaDescStyle, children: description }),
@@ -629,11 +668,14 @@ function SchemaLeaf({ schema }) {
     ] })
   ] });
 }
-function FieldRows({ fields }) {
+function FieldRows({
+  fields,
+  verbatim = false
+}) {
   if (fields.length === 0) return null;
   return /* @__PURE__ */ jsx("dl", { className: listStyle$1, children: fields.map(([field, value]) => /* @__PURE__ */ jsxs("div", { className: rowStyle$1, children: [
-    /* @__PURE__ */ jsx("dt", { className: nameStyle$1, children: humanizeField(field) }),
-    /* @__PURE__ */ jsx("dd", { className: valueStyle, children: renderValue(value) })
+    /* @__PURE__ */ jsx("dt", { className: nameStyle$1, children: verbatim ? field : humanizeField(field) }),
+    /* @__PURE__ */ jsx("dd", { className: valueStyle, children: renderValue(value, verbatim) })
   ] }, field)) });
 }
 const listStyle$1 = css({
@@ -754,7 +796,11 @@ function BindingsSection({ bindings, title = "Bindings" }) {
       );
       return /* @__PURE__ */ jsxs("div", { className: protocolCardStyle, children: [
         /* @__PURE__ */ jsx("div", { className: protocolHeaderStyle, children: /* @__PURE__ */ jsx(ProtocolBadge, { protocol }) }),
-        rows.length > 0 ? /* @__PURE__ */ jsx(FieldRows, { fields: rows }) : /* @__PURE__ */ jsx("p", { className: emptyStyle, children: "No binding fields." })
+        rows.length > 0 ? (
+          // Binding/config keys are shown verbatim — their acronyms (URL,
+          // ID) and dotted names (cleanup.policy) must not be title-cased.
+          /* @__PURE__ */ jsx(FieldRows, { fields: rows, verbatim: true })
+        ) : /* @__PURE__ */ jsx("p", { className: emptyStyle, children: "No binding fields." })
       ] }, protocol);
     }) })
   ] });
@@ -792,17 +838,20 @@ function SecurityRequirementBadges({ requirements, label = "Security" }) {
   if (!requirements || requirements.length === 0) return null;
   return /* @__PURE__ */ jsxs("div", { className: rowStyle, children: [
     /* @__PURE__ */ jsx("span", { className: labelStyle, children: label }),
-    requirements.map((alternative, altIndex) => /* @__PURE__ */ jsxs(Fragment, { children: [
-      altIndex > 0 && /* @__PURE__ */ jsx("span", { className: orStyle, children: "OR" }),
-      alternative.map((scheme) => /* @__PURE__ */ jsxs("a", { href: `#security-${scheme.name}`, className: badgeStyle, children: [
+    requirements.map((alternative, altIndex) => {
+      const chips = alternative.map((scheme) => /* @__PURE__ */ jsxs("a", { href: `#security-${scheme.name}`, className: badgeStyle, children: [
         /* @__PURE__ */ jsx(Icon, { name: "lock", size: "0.625rem", strokeWidth: 2.5 }),
         scheme.name,
         scheme.scopes.length > 0 && /* @__PURE__ */ jsxs("span", { className: scopesStyle$1, children: [
           /* @__PURE__ */ jsx("span", { className: scopeSepStyle, children: "\xB7" }),
           scheme.scopes.join(", ")
         ] })
-      ] }, scheme.name))
-    ] }, altIndex))
+      ] }, scheme.name));
+      return altIndex === 0 ? /* @__PURE__ */ jsx(Fragment, { children: chips }, altIndex) : /* @__PURE__ */ jsxs("span", { className: orGroupStyle, children: [
+        /* @__PURE__ */ jsx("span", { className: orStyle, children: "OR" }),
+        chips
+      ] }, altIndex);
+    })
   ] });
 }
 const rowStyle = css({
@@ -810,7 +859,16 @@ const rowStyle = css({
   alignItems: "center",
   gap: "0.375rem",
   flexWrap: "wrap",
-  marginTop: "0.5rem"
+  marginTop: "0.5rem",
+  // Breathing room below the security row so it doesn't butt against the next
+  // section on narrow screens (finding 3).
+  marginBottom: "0.5rem"
+});
+const orGroupStyle = css({
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "0.375rem",
+  whiteSpace: "nowrap"
 });
 const labelStyle = css({
   fontSize: "var(--omnispec-font-size-xxs)",
@@ -955,9 +1013,9 @@ const varTokenStyle = css({
   "&::after": { content: '"}"' }
 });
 function highlightVariables(url) {
-  const parts = url.split(/(\{[^}]+\})/g);
+  const parts = url.split(/(\{[^{}]+\})/g);
   return parts.map(
-    (part, i) => /^\{[^}]+\}$/.test(part) ? /* @__PURE__ */ jsx("span", { className: varTokenStyle, children: part.slice(1, -1) }, i) : /* @__PURE__ */ jsx("span", { children: part }, i)
+    (part, i) => /^\{[^{}]+\}$/.test(part) ? /* @__PURE__ */ jsx("span", { className: varTokenStyle, children: part.slice(1, -1) }, i) : /* @__PURE__ */ jsx("span", { children: part }, i)
   );
 }
 function ServerCard({ server }) {
@@ -1008,6 +1066,56 @@ function ServerList({ servers }) {
   ] });
 }
 
+function TagChips({ tags, onTagClick }) {
+  if (!tags || tags.length === 0) return null;
+  return /* @__PURE__ */ jsx("div", { className: tagChipsStyle$1, children: tags.map((tag) => /* @__PURE__ */ jsxs("span", { className: tagItemStyle, children: [
+    onTagClick ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className: tagChipButtonStyle$1,
+        title: tag.description,
+        onClick: () => onTagClick(tag.name),
+        children: tag.name
+      }
+    ) : /* @__PURE__ */ jsx("span", { className: tagChipStyle$1, title: tag.description, children: tag.name }),
+    tag.externalDocs && /* @__PURE__ */ jsx(ExternalDocsLink, { externalDocs: tag.externalDocs, context: tag.name })
+  ] }, tag.name)) });
+}
+const tagChipsStyle$1 = css({
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "0.5rem",
+  marginBottom: "0.5rem"
+});
+const tagItemStyle = css({
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "0.25rem"
+});
+const tagChipStyle$1 = css({
+  fontSize: "var(--omnispec-font-size-xxs)",
+  fontFamily: "var(--omnispec-font-mono)",
+  color: "var(--omnispec-fg-secondary)",
+  backgroundColor: "var(--omnispec-bg-tertiary)",
+  padding: "1px 0.5rem",
+  borderRadius: "0.625rem"
+});
+const tagChipButtonStyle$1 = css({
+  fontSize: "var(--omnispec-font-size-xxs)",
+  fontFamily: "var(--omnispec-font-mono)",
+  color: "var(--omnispec-fg-secondary)",
+  backgroundColor: "var(--omnispec-bg-tertiary)",
+  padding: "1px 0.5rem",
+  borderRadius: "0.625rem",
+  border: "none",
+  cursor: "pointer",
+  "&:hover": {
+    color: "var(--omnispec-fg-primary)"
+  }
+});
+
 function detectSchemaFormat(schemaFormat) {
   if (!schemaFormat) return "json";
   const f = schemaFormat.toLowerCase();
@@ -1086,7 +1194,11 @@ function primitive(name) {
 function MessagePayload({ message, idx }) {
   const rawPayload = message.payload;
   return /* @__PURE__ */ jsxs(Fragment$1, { children: [
-    message.tags && message.tags.length > 0 && /* @__PURE__ */ jsx("div", { className: tagChipsStyle$2, children: message.tags.map((tag) => /* @__PURE__ */ jsx("span", { className: tagChipStyle$2, title: tag.description, children: tag.name }, tag.name)) }),
+    message.tags && message.tags.length > 0 && /* @__PURE__ */ jsx(TagChips, { tags: message.tags }),
+    message.appliedTraits && message.appliedTraits.length > 0 && /* @__PURE__ */ jsxs("div", { className: traitsRowStyle, children: [
+      /* @__PURE__ */ jsx("span", { className: traitsLabelStyle, children: "Traits:" }),
+      message.appliedTraits.map((trait, i) => /* @__PURE__ */ jsx("code", { className: traitChipStyle, children: trait }, `${trait}-${i}`))
+    ] }),
     message.externalDocs && /* @__PURE__ */ jsx("div", { className: externalDocsStyle, children: /* @__PURE__ */ jsx(
       ExternalDocsLink,
       {
@@ -1115,10 +1227,23 @@ function PayloadBody({
   }
   const format = detectSchemaFormat(schemaFormat);
   if (format === "protobuf") {
-    return /* @__PURE__ */ jsxs("div", { children: [
-      /* @__PURE__ */ jsx(CodeBlock, { code: JSON.stringify(rawPayload, null, 2), language: "json" }),
-      /* @__PURE__ */ jsx("p", { className: proNoteStyle, children: "Full Protobuf schema rendering is available in Pro." })
-    ] });
+    const isSource = typeof rawPayload === "string";
+    const code = isSource ? rawPayload : JSON.stringify(rawPayload, null, 2);
+    return /* @__PURE__ */ jsx(
+      Tabs,
+      {
+        tabs: [
+          {
+            id: `schema-${idx}`,
+            label: "Payload Schema",
+            content: /* @__PURE__ */ jsxs("div", { children: [
+              /* @__PURE__ */ jsx(CodeBlock, { code, language: isSource ? "text" : "json" }),
+              /* @__PURE__ */ jsx("p", { className: proNoteStyle, children: "Full Protobuf schema rendering is available in Pro." })
+            ] })
+          }
+        ]
+      }
+    );
   }
   const schema = format === "avro" ? avroToJsonSchema(rawPayload) : rawPayload;
   return /* @__PURE__ */ jsx(
@@ -1154,22 +1279,28 @@ function MessageExample({ message, schema }) {
     /* @__PURE__ */ jsx(CodeBlock, { code, language: "json" })
   ] });
 }
-const tagChipsStyle$2 = css({
+const externalDocsStyle = css({
+  marginBottom: "0.5rem"
+});
+const traitsRowStyle = css({
   display: "flex",
+  alignItems: "center",
   flexWrap: "wrap",
-  gap: "0.25rem",
+  gap: "0.375rem",
   marginBottom: "0.5rem"
 });
-const tagChipStyle$2 = css({
-  fontSize: "var(--omnispec-font-size-xxs)",
+const traitsLabelStyle = css({
+  fontSize: "var(--omnispec-font-size-xs)",
+  fontWeight: 700,
+  color: "var(--omnispec-fg-muted)"
+});
+const traitChipStyle = css({
   fontFamily: "var(--omnispec-font-mono)",
+  fontSize: "var(--omnispec-font-size-xxs)",
   color: "var(--omnispec-fg-secondary)",
   backgroundColor: "var(--omnispec-bg-tertiary)",
-  padding: "1px 0.5rem",
-  borderRadius: "0.625rem"
-});
-const externalDocsStyle = css({
-  marginBottom: "0.5rem"
+  padding: "0.0625rem 0.375rem",
+  borderRadius: "var(--omnispec-border-radius)"
 });
 const schemaFormatBadgeStyle = css({
   display: "inline-block",
@@ -1230,6 +1361,7 @@ function ChannelDetail({ channel, id, expandAll, expandGeneration, onTagClick })
         /* @__PURE__ */ jsx(MethodBar, { label: primaryLabel, path: channel.address, color: primaryColor }),
         /* @__PURE__ */ jsxs("div", { className: bodyStyle, children: [
           channel.description && /* @__PURE__ */ jsx("div", { className: sectionStyle$1, children: /* @__PURE__ */ jsx(MarkdownRenderer, { content: channel.description }) }),
+          channel.tags && channel.tags.length > 0 && /* @__PURE__ */ jsx(TagChips, { tags: channel.tags, onTagClick }),
           channel.externalDocs && /* @__PURE__ */ jsx("div", { className: sectionStyle$1, children: /* @__PURE__ */ jsx(ExternalDocsLink, { externalDocs: channel.externalDocs, context: channel.address }) }),
           channel.parameters && Object.keys(channel.parameters).length > 0 && /* @__PURE__ */ jsxs("div", { className: sectionStyle$1, children: [
             /* @__PURE__ */ jsx("h4", { className: sectionTitleStyle$1, children: "Parameters" }),
@@ -1259,32 +1391,22 @@ function ChannelDetail({ channel, id, expandAll, expandGeneration, onTagClick })
           /* @__PURE__ */ jsx(BindingsSection, { bindings: channel.bindings, title: "Channel Bindings" }),
           channel.operations.map((op, idx) => /* @__PURE__ */ jsxs("div", { id: id ? `${id}-op-${idx}` : void 0, className: operationStyle, children: [
             /* @__PURE__ */ jsxs("div", { className: opHeaderStyle$1, children: [
-              /* @__PURE__ */ jsx(
-                "span",
-                {
-                  className: cx(actionBadgeBase$1, css({
-                    backgroundColor: actionColors$1[op.action] ?? "var(--omnispec-fg-muted)"
-                  })),
-                  children: actionLabels$1[op.action] ?? op.action.toUpperCase()
-                }
-              ),
-              op.operationId && /* @__PURE__ */ jsx("span", { className: opIdStyle$1, children: op.operationId }),
-              op.title && /* @__PURE__ */ jsx("span", { className: opTitleStyle$1, children: op.title }),
+              /* @__PURE__ */ jsxs("span", { className: opNameLineStyle, children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: cx(actionBadgeBase$1, css({
+                      backgroundColor: actionColors$1[op.action] ?? "var(--omnispec-fg-muted)"
+                    })),
+                    children: actionLabels$1[op.action] ?? op.action.toUpperCase()
+                  }
+                ),
+                op.operationId && /* @__PURE__ */ jsx("span", { className: opIdStyle$1, children: op.operationId }),
+                op.title && /* @__PURE__ */ jsx("span", { className: opTitleStyle$1, children: op.title })
+              ] }),
               op.summary && /* @__PURE__ */ jsx("span", { className: opSummaryStyle$1, children: op.summary })
             ] }),
-            op.tags && op.tags.length > 0 && /* @__PURE__ */ jsx("div", { className: tagChipsStyle$1, children: op.tags.map(
-              (tag) => onTagClick ? /* @__PURE__ */ jsx(
-                "button",
-                {
-                  type: "button",
-                  className: tagChipButtonStyle$1,
-                  title: tag.description,
-                  onClick: () => onTagClick(tag.name),
-                  children: tag.name
-                },
-                tag.name
-              ) : /* @__PURE__ */ jsx("span", { className: tagChipStyle$1, title: tag.description, children: tag.name }, tag.name)
-            ) }),
+            op.tags && op.tags.length > 0 && /* @__PURE__ */ jsx(TagChips, { tags: op.tags, onTagClick }),
             op.description && /* @__PURE__ */ jsx("div", { className: sectionStyle$1, children: /* @__PURE__ */ jsx(MarkdownRenderer, { content: op.description }) }),
             op.externalDocs && /* @__PURE__ */ jsx("div", { className: opExternalDocsStyle, children: /* @__PURE__ */ jsx(
               ExternalDocsLink,
@@ -1301,8 +1423,9 @@ function ChannelDetail({ channel, id, expandAll, expandGeneration, onTagClick })
                 /* @__PURE__ */ jsx("span", { className: replyMetaLabelStyle, children: "channel" }),
                 /* @__PURE__ */ jsx("code", { className: replyMetaValueStyle, children: op.reply.channelName })
               ] }),
-              op.reply.address && (op.reply.address.location || op.reply.address.description) && /* @__PURE__ */ jsxs("div", { className: replyMetaRowStyle, children: [
+              op.reply.address && (op.reply.address.value || op.reply.address.location || op.reply.address.description) && /* @__PURE__ */ jsxs("div", { className: replyMetaRowStyle, children: [
                 /* @__PURE__ */ jsx("span", { className: replyMetaLabelStyle, children: "address" }),
+                op.reply.address.value && /* @__PURE__ */ jsx("code", { className: replyMetaValueStyle, children: op.reply.address.value }),
                 op.reply.address.location && /* @__PURE__ */ jsx("code", { className: replyMetaValueStyle, children: op.reply.address.location }),
                 op.reply.address.description && /* @__PURE__ */ jsx("span", { className: replyMetaDescStyle, children: op.reply.address.description })
               ] }),
@@ -1356,10 +1479,10 @@ function MessageView({ message, idx }) {
     message.summary && /* @__PURE__ */ jsx("p", { className: messageSummaryStyle$1, children: message.summary }),
     message.contentType && /* @__PURE__ */ jsx("code", { className: contentTypeStyle$2, children: message.contentType }),
     /* @__PURE__ */ jsx(MessagePayload, { message, idx }),
-    message.correlationId && /* @__PURE__ */ jsxs("div", { className: correlationIdStyle, children: [
-      /* @__PURE__ */ jsx("span", { className: correlationIdLabelStyle, children: "correlationId" }),
-      /* @__PURE__ */ jsx("code", { className: correlationIdLocationStyle, children: message.correlationId.location }),
-      message.correlationId.description && /* @__PURE__ */ jsx("span", { className: correlationIdDescStyle, children: message.correlationId.description })
+    message.correlationId && /* @__PURE__ */ jsxs("div", { className: correlationIdStyle$1, children: [
+      /* @__PURE__ */ jsx("span", { className: correlationIdLabelStyle$1, children: "correlationId" }),
+      /* @__PURE__ */ jsx("code", { className: correlationIdLocationStyle$1, children: message.correlationId.location }),
+      message.correlationId.description && /* @__PURE__ */ jsx("span", { className: correlationIdDescStyle$1, children: message.correlationId.description })
     ] }),
     message.headers && /* @__PURE__ */ jsxs("div", { className: headersWrapStyle$1, children: [
       /* @__PURE__ */ jsx("h4", { className: sectionTitleStyle$1, children: "Headers" }),
@@ -1426,9 +1549,16 @@ const operationStyle = css({
 const opHeaderStyle$1 = css({
   display: "flex",
   alignItems: "center",
-  gap: "0.5rem",
+  flexWrap: "wrap",
+  gap: "0.25rem 0.5rem",
   marginBottom: "0.5rem"
 });
+const opNameLineStyle = css({
+  display: "inline-flex",
+  alignItems: "center",
+  flexWrap: "wrap",
+  gap: "0.5rem"
+});
 const actionBadgeBase$1 = css({
   display: "inline-block",
   padding: "0.125rem 0.375rem",
@@ -1451,6 +1581,7 @@ const opTitleStyle$1 = css({
   color: "var(--omnispec-fg-primary)"
 });
 const opSummaryStyle$1 = css({
+  flexBasis: "100%",
   fontSize: "var(--omnispec-font-size-sm)",
   color: "var(--omnispec-fg-secondary)"
 });
@@ -1506,20 +1637,20 @@ const messageCountStyle = css({
   fontSize: "var(--omnispec-font-size-xs)",
   color: "var(--omnispec-fg-muted)"
 });
-const correlationIdStyle = css({
+const correlationIdStyle$1 = css({
   display: "flex",
   alignItems: "center",
   gap: "0.5rem",
   flexWrap: "wrap",
   marginTop: "0.75rem"
 });
-const correlationIdLabelStyle = css({
+const correlationIdLabelStyle$1 = css({
   fontSize: "var(--omnispec-font-size-xs)",
   fontWeight: 700,
   color: "var(--omnispec-fg-primary)",
   fontFamily: "var(--omnispec-font-mono)"
 });
-const correlationIdLocationStyle = css({
+const correlationIdLocationStyle$1 = css({
   fontFamily: "var(--omnispec-font-mono)",
   fontSize: "var(--omnispec-font-size-xs)",
   color: "var(--omnispec-fg-code)",
@@ -1527,7 +1658,7 @@ const correlationIdLocationStyle = css({
   padding: "1px 0.375rem",
   borderRadius: "0.1875rem"
 });
-const correlationIdDescStyle = css({
+const correlationIdDescStyle$1 = css({
   fontSize: "var(--omnispec-font-size-xs)",
   color: "var(--omnispec-fg-secondary)"
 });
@@ -1568,33 +1699,6 @@ const replyMetaDescStyle = css({
   fontSize: "var(--omnispec-font-size-xs)",
   color: "var(--omnispec-fg-secondary)"
 });
-const tagChipsStyle$1 = css({
-  display: "flex",
-  flexWrap: "wrap",
-  gap: "0.25rem",
-  marginBottom: "0.5rem"
-});
-const tagChipStyle$1 = css({
-  fontSize: "var(--omnispec-font-size-xxs)",
-  fontFamily: "var(--omnispec-font-mono)",
-  color: "var(--omnispec-fg-secondary)",
-  backgroundColor: "var(--omnispec-bg-tertiary)",
-  padding: "1px 0.5rem",
-  borderRadius: "0.625rem"
-});
-const tagChipButtonStyle$1 = css({
-  fontSize: "var(--omnispec-font-size-xxs)",
-  fontFamily: "var(--omnispec-font-mono)",
-  color: "var(--omnispec-fg-secondary)",
-  backgroundColor: "var(--omnispec-bg-tertiary)",
-  padding: "1px 0.5rem",
-  borderRadius: "0.625rem",
-  border: "none",
-  cursor: "pointer",
-  "&:hover": {
-    color: "var(--omnispec-fg-primary)"
-  }
-});
 
 const actionLabels = {
   publish: "PUB",
@@ -1900,11 +2004,13 @@ function ComponentsSection({ components }) {
           children: [
             message.title && /* @__PURE__ */ jsx("p", { className: messageSummaryStyle, children: message.title }),
             message.summary && /* @__PURE__ */ jsx("p", { className: messageSummaryStyle, children: message.summary }),
-            message.contentType && /* @__PURE__ */ jsxs("code", { className: contentTypeStyle, children: [
-              message.contentType,
-              message.contentTypeInherited && /* @__PURE__ */ jsx("span", { className: contentTypeHintStyle, children: " (default)" })
-            ] }),
+            message.contentType && /* @__PURE__ */ jsx("code", { className: contentTypeStyle, children: message.contentType }),
             /* @__PURE__ */ jsx(MessagePayload, { message, idx: `message-${name}` }),
+            message.correlationId && /* @__PURE__ */ jsxs("div", { className: correlationIdStyle, children: [
+              /* @__PURE__ */ jsx("span", { className: correlationIdLabelStyle, children: "correlationId" }),
+              /* @__PURE__ */ jsx("code", { className: correlationIdLocationStyle, children: message.correlationId.location }),
+              message.correlationId.description && /* @__PURE__ */ jsx("span", { className: correlationIdDescStyle, children: message.correlationId.description })
+            ] }),
             message.headers && /* @__PURE__ */ jsxs("div", { className: headersWrapStyle, children: [
               /* @__PURE__ */ jsx("h4", { className: headersTitleStyle, children: "Headers" }),
               /* @__PURE__ */ jsx(SchemaTree, { nodes: schemaToNodes(message.headers) })
@@ -1973,9 +2079,30 @@ const contentTypeStyle = css({
   color: "var(--omnispec-fg-muted)",
   marginBottom: "0.5rem"
 });
-const contentTypeHintStyle = css({
-  fontStyle: "italic",
-  color: "var(--omnispec-fg-muted)"
+const correlationIdStyle = css({
+  display: "flex",
+  alignItems: "center",
+  gap: "0.5rem",
+  flexWrap: "wrap",
+  marginTop: "0.75rem"
+});
+const correlationIdLabelStyle = css({
+  fontSize: "var(--omnispec-font-size-xs)",
+  fontWeight: 700,
+  color: "var(--omnispec-fg-primary)",
+  fontFamily: "var(--omnispec-font-mono)"
+});
+const correlationIdLocationStyle = css({
+  fontFamily: "var(--omnispec-font-mono)",
+  fontSize: "var(--omnispec-font-size-xs)",
+  color: "var(--omnispec-fg-code)",
+  backgroundColor: "var(--omnispec-bg-tertiary)",
+  padding: "1px 0.375rem",
+  borderRadius: "0.1875rem"
+});
+const correlationIdDescStyle = css({
+  fontSize: "var(--omnispec-font-size-xs)",
+  color: "var(--omnispec-fg-secondary)"
 });
 const headersWrapStyle = css({
   marginTop: "1rem"
@@ -2135,7 +2262,7 @@ const scopeDescStyle = css({
 
 const UNTAGGED_LABEL = "Untagged";
 function slugify(value) {
-  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tag";
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "tag";
 }
 function channelTagNames(channel) {
   const names = /* @__PURE__ */ new Set();
@@ -2148,7 +2275,7 @@ function channelTagNames(channel) {
 function hasAnyTags(channels) {
   return channels.some((ch) => channelTagNames(ch).length > 0);
 }
-function groupChannelsByTag(channels, specTags) {
+function groupChannelsByTag(channels, specTags, xTagGroups) {
   const byName = /* @__PURE__ */ new Map();
   const untagged = [];
   for (const channel of channels) {
@@ -2163,9 +2290,13 @@ function groupChannelsByTag(channels, specTags) {
       byName.set(name, list);
     }
   }
+  const xGrouped = (xTagGroups ?? []).flatMap((xg) => xg.tags).filter((name) => byName.has(name));
   const declared = (specTags ?? []).map((t) => t.name);
-  const operationOnly = Array.from(byName.keys()).filter((name) => !declared.includes(name)).sort();
-  const orderedNames = [...declared.filter((name) => byName.has(name)), ...operationOnly];
+  const seen = new Set(xGrouped);
+  const declaredRemaining = declared.filter((name) => byName.has(name) && !seen.has(name));
+  declaredRemaining.forEach((name) => seen.add(name));
+  const operationOnly = Array.from(byName.keys()).filter((name) => !seen.has(name)).sort();
+  const orderedNames = [.../* @__PURE__ */ new Set([...xGrouped, ...declaredRemaining, ...operationOnly])];
   const tagMetaByName = new Map((specTags ?? []).map((t) => [t.name, t]));
   const usedIds = /* @__PURE__ */ new Set();
   const uniqueId = (base) => {
@@ -2252,10 +2383,26 @@ function AsyncApiSpec({
   const [allExpanded, setAllExpanded] = useState(defaultExpandOperations);
   const [expandGeneration, setExpandGeneration] = useState(0);
   const [navGrouping, setNavGrouping] = useState("channel");
+  const [activeTagFilter, setActiveTagFilter] = useState(null);
   const handleToggleExpand = useCallback(() => {
     setAllExpanded((prev) => !prev);
     setExpandGeneration((prev) => prev + 1);
   }, []);
+  const handleTagFilter = useCallback((tagName) => {
+    setActiveTagFilter((prev) => {
+      const next = prev === tagName ? null : tagName;
+      setSearchQuery(next ?? "");
+      return next;
+    });
+  }, []);
+  const handleSearch = useCallback((query) => {
+    setSearchQuery(query);
+    setActiveTagFilter(null);
+  }, []);
+  const clearTagFilter = useCallback(() => {
+    setActiveTagFilter(null);
+    setSearchQuery("");
+  }, []);
   useMemo(() => {
     if (parsedSpec && onSpecLoaded) {
       const major = parseInt(parsedSpec.specVersion.split(".")[0], 10);
@@ -2277,7 +2424,7 @@ function AsyncApiSpec({
   }, [parsedSpec, searchQuery]);
   const grouped = useMemo(() => hasAnyTags(filteredChannels), [filteredChannels]);
   const tagGroups = useMemo(
-    () => grouped ? groupChannelsByTag(filteredChannels, parsedSpec?.tags) : [],
+    () => grouped ? groupChannelsByTag(filteredChannels, parsedSpec?.tags, parsedSpec?.tagGroups) : [],
     [grouped, filteredChannels, parsedSpec]
   );
   const channelDomId = useMemo(() => {
@@ -2309,6 +2456,10 @@ function AsyncApiSpec({
     () => filteredChannels.some((ch) => ch.operations.length > 0),
     [filteredChannels]
   );
+  const unassignedOpCount = useMemo(
+    () => parsedSpec?.channels.filter((ch) => ch.name === "__unassigned__").reduce((sum, ch) => sum + ch.operations.length, 0) ?? 0,
+    [parsedSpec]
+  );
   const navItems = useMemo(() => {
     if (!parsedSpec) return [];
     const actionLabel = (action) => action.toUpperCase();
@@ -2411,9 +2562,27 @@ function AsyncApiSpec({
       SearchBar,
       {
         placeholder: "Filter channels...",
-        onSearch: setSearchQuery
+        onSearch: handleSearch,
+        value: searchQuery
       }
     ),
+    activeTagFilter && /* @__PURE__ */ jsxs("div", { className: activeFilterStyle, children: [
+      /* @__PURE__ */ jsx("span", { className: activeFilterLabelStyle, children: "Filtered by tag:" }),
+      /* @__PURE__ */ jsx("span", { className: activeFilterTagStyle, children: activeTagFilter }),
+      /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
+          className: activeFilterClearStyle,
+          onClick: clearTagFilter,
+          "aria-label": `Clear tag filter: ${activeTagFilter}`,
+          children: [
+            "Clear",
+            /* @__PURE__ */ jsx(Icon, { name: "xmark", size: "0.75rem", strokeWidth: 2.5 })
+          ]
+        }
+      )
+    ] }),
     hasOperations && /* @__PURE__ */ jsxs("div", { className: groupToggleStyle, role: "group", "aria-label": "Sidebar grouping", children: [
       /* @__PURE__ */ jsx("span", { className: groupToggleLabelStyle, children: "Group by" }),
       /* @__PURE__ */ jsxs("div", { className: groupToggleButtonsStyle, children: [
@@ -2476,6 +2645,7 @@ function AsyncApiSpec({
         /* @__PURE__ */ jsx("div", { id: "servers", children: /* @__PURE__ */ jsx(ServerList, { servers: parsedSpec.servers }) }),
         /* @__PURE__ */ jsxs("div", { id: "channels", children: [
           /* @__PURE__ */ jsx("h2", { className: css({ margin: "0 0 1rem", fontSize: "var(--omnispec-h2-font-size)", fontWeight: "var(--omnispec-h2-font-weight)", color: "var(--omnispec-h2-color)" }), children: "Channels" }),
+          unassignedOpCount > 0 && /* @__PURE__ */ jsx("p", { className: unassignedNoticeStyle, role: "alert", children: `Unresolved reference: ${unassignedOpCount} ${unassignedOpCount === 1 ? "operation references" : "operations reference"} an undefined channel. ${unassignedOpCount === 1 ? "It is" : "They are"} listed under "Unassigned operations" below rather than dropped.` }),
           filteredChannels.length === 0 ? /* @__PURE__ */ jsx("p", { className: emptyStateStyle, children: parsedSpec.channels.length === 0 ? "No channels are defined for this API." : "No channels match your filter." }) : grouped ? tagGroups.map((group) => /* @__PURE__ */ jsxs("section", { id: `taggroup-${group.id}`, className: tagSectionStyle, children: [
             /* @__PURE__ */ jsx(TagGroupHeader, { group }),
             group.channels.map((channel) => /* @__PURE__ */ jsx(
@@ -2486,7 +2656,7 @@ function AsyncApiSpec({
                 displayMode: resolvedDisplayMode,
                 expandAll: allExpanded,
                 expandGeneration,
-                onTagClick: setSearchQuery
+                onTagClick: handleTagFilter
               },
               `${group.id}-${channel.name}`
             ))
@@ -2498,7 +2668,7 @@ function AsyncApiSpec({
               displayMode: resolvedDisplayMode,
               expandAll: allExpanded,
               expandGeneration,
-              onTagClick: setSearchQuery
+              onTagClick: handleTagFilter
             },
             channel.name
           ))
@@ -2538,7 +2708,7 @@ function nestByTagGroups(groups, xTagGroups, toNav) {
     const children = xg.tags.map((t) => byTagName.get(t)).filter((g) => !!g);
     children.forEach((g) => used.add(g));
     return {
-      id: `xtaggroup-${xg.name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "group"}`,
+      id: `xtaggroup-${xg.name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "group"}`,
       label: xg.name,
       children: children.map(toNav)
     };
@@ -2551,6 +2721,17 @@ const emptyStateStyle = css({
   color: "var(--omnispec-fg-muted)",
   fontStyle: "italic"
 });
+const unassignedNoticeStyle = css({
+  display: "flex",
+  alignItems: "center",
+  gap: "0.5rem",
+  padding: "0.625rem 0.875rem",
+  marginBottom: "1rem",
+  borderRadius: "var(--omnispec-border-radius)",
+  backgroundColor: "color-mix(in srgb, var(--omnispec-color-warning) 12%, transparent)",
+  color: "var(--omnispec-color-warning)",
+  fontSize: "var(--omnispec-font-size-sm)"
+});
 const noResultsNavStyle = css({
   fontStyle: "italic",
   color: "var(--omnispec-fg-muted)",
@@ -2594,6 +2775,48 @@ const groupToggleActiveStyle = css({
 const tagSectionStyle = css({
   marginBottom: "2rem"
 });
+const activeFilterStyle = css({
+  display: "flex",
+  alignItems: "center",
+  flexWrap: "wrap",
+  gap: "0.375rem",
+  padding: "0 0.75rem 0.5rem"
+});
+const activeFilterLabelStyle = css({
+  fontSize: "var(--omnispec-font-size-xxs)",
+  fontWeight: 600,
+  textTransform: "uppercase",
+  letterSpacing: "0.05em",
+  color: "var(--omnispec-fg-muted)"
+});
+const activeFilterTagStyle = css({
+  fontFamily: "var(--omnispec-font-mono)",
+  fontSize: "var(--omnispec-font-size-xs)",
+  fontWeight: 500,
+  color: "var(--omnispec-fg-primary)",
+  backgroundColor: "var(--omnispec-bg-tertiary)",
+  padding: "0.125rem 0.5rem",
+  borderRadius: "var(--omnispec-border-radius)"
+});
+const activeFilterClearStyle = css({
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "0.1875rem",
+  border: "none",
+  background: "transparent",
+  cursor: "pointer",
+  marginLeft: "auto",
+  padding: "0.125rem 0.25rem",
+  borderRadius: "var(--omnispec-border-radius)",
+  fontSize: "var(--omnispec-font-size-xxs)",
+  fontWeight: 600,
+  textTransform: "uppercase",
+  letterSpacing: "0.05em",
+  color: "var(--omnispec-color-primary)",
+  "&:hover": {
+    backgroundColor: "var(--omnispec-bg-tertiary)"
+  }
+});
 
 export { AsyncApiSpec };
-//# sourceMappingURL=AsyncApiSpec-BzhfaQ_T.js.map
+//# sourceMappingURL=AsyncApiSpec-C0tdvyEP.js.map