blume 2.0.1 → 2.0.2

package/src/components/layout/Search.astro

@@ -67,6 +67,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-i18n-dev={s.devOnly}
   data-i18n-empty={s.noResults}
   data-i18n-error={s.error}
+  data-i18n-latest={s.latest}
   data-i18n-popular={s.popular}
   data-i18n-results={s.results}
   data-locale={locale || undefined}
@@ -328,6 +329,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       allMsg = "All";
       popularMsg = "Popular";
       resultsMsg = "Results";
+      latestMsg = "latest";
       // The active locale to filter to (null when i18n is off), and whether the
       // reader has opted to search across every language instead.
       locale: string | null = null;
@@ -382,6 +384,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.getAttribute("data-i18n-popular") || this.popularMsg;
         this.resultsMsg =
           this.getAttribute("data-i18n-results") || this.resultsMsg;
+        this.latestMsg =
+          this.getAttribute("data-i18n-latest") || this.latestMsg;
         this.locale = this.getAttribute("data-locale");
         // "" (the current docs) is a real version value, so a presence flag —
         // not the attribute's truthiness — decides whether filtering is on.
@@ -765,7 +769,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         // reader knows they're about to leave the docs they're viewing.
         const versionTag =
           this.versioned && hit.version !== undefined && hit.version !== this.version
-            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || "latest")}</span>`
+            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || this.latestMsg)}</span>`
             : "";
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>

package/src/components/layout/analytics-client.ts

@@ -29,6 +29,7 @@ interface AnalyticsWindow {
   analytics?: { track?: (event: string, props?: TrackProps) => void };
   clarity?: (command: "event", event: string) => void;
   dataLayer?: DataLayer;
+  databuddy?: { track?: (event: string, props?: TrackProps) => void };
   fathom?: { trackEvent?: (event: string) => void };
   gtag?: (command: "event", event: string, props?: TrackProps) => void;
   heap?: { track?: (event: string, props?: TrackProps) => void };
@@ -82,6 +83,7 @@ const trackGlobals = (
   attempt(() => (w.__blumeGtmLayer ?? w.dataLayer)?.push({ ...props, event }));
   // Privacy-first counters take a name, some with properties.
   attempt(() => w.plausible?.(event, { props }));
+  attempt(() => w.databuddy?.track?.(event, props));
   attempt(() => w.fathom?.trackEvent?.(event));
   // Pirsch stringifies `meta` values in place, so it gets its own copy and
   // the `blume:track` listeners still see the original types.

package/src/components/openapi/GraphqlType.astro

@@ -1,4 +1,5 @@
 ---
+import { isSafeHref } from "../../core/safe-href.ts";
 import type { GraphqlDocument } from "../../openapi/graphql.ts";
 import { graphqlTypeDef } from "../../openapi/graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "../../openapi/model.ts";
@@ -65,9 +66,16 @@ const SECTION_HEADING = "mb-2 font-semibold text-foreground text-sm";
       {type.specifiedByUrl && (
         <div class="mb-4 text-muted-foreground text-sm">
           Specified by{" "}
-          <a class="text-accent hover:underline" href={type.specifiedByUrl}>
-            {type.specifiedByUrl}
-          </a>
+          {/* The URL comes from the schema, someone else's content: a
+              `javascript:` one would run on the docs origin when clicked, so
+              only a safe destination becomes a link. */}
+          {isSafeHref(type.specifiedByUrl) ? (
+            <a class="text-accent hover:underline" href={type.specifiedByUrl}>
+              {type.specifiedByUrl}
+            </a>
+          ) : (
+            <code class="break-all">{type.specifiedByUrl}</code>
+          )}
         </div>
       )}
       <GraphqlFieldsTable

package/src/components/openapi/MessageComposer.astro

@@ -133,7 +133,7 @@ const BUTTON_QUIET =
           Payload
           {
             model.payload.contentType && (
-              <span class="ml-1.5 font-mono normal-case">
+              <span class="ms-1.5 font-mono normal-case">
                 {model.payload.contentType}
               </span>
             )

package/src/components/openapi/Operation.astro

@@ -6,8 +6,13 @@ import {
   type ParameterLike,
   resolveComponentRef,
   type SchemaLike,
+  type SpecValue,
 } from "./helpers.ts";
-import { operationModel } from "./operation-model.ts";
+import {
+  effectiveServers,
+  operationModel,
+  type ServerLike,
+} from "./operation-model.ts";
 import { buildRequest, defaultValues } from "./request.ts";
 import {
   effectiveSecurity,
@@ -35,7 +40,8 @@ interface Props {
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
 interface RequestBodyLike {
@@ -59,6 +65,7 @@ interface FullOperation {
   requestBody?: RequestBodyLike;
   responses?: Record<string, ResponseLike>;
   security?: SecurityRequirementLike[];
+  servers?: ServerLike[];
 }
 
 const { source, id } = Astro.props;
@@ -73,7 +80,10 @@ const isGraphql = spec?.kind === "graphql";
 const doc = (spec?.document ?? {}) as {
   paths?: Record<
     string,
-    Record<string, unknown> & { parameters?: ParameterLike[] }
+    Record<string, unknown> & {
+      parameters?: ParameterLike[];
+      servers?: ServerLike[];
+    }
   >;
   components?: {
     schemas?: Record<string, SchemaLike>;
@@ -83,7 +93,7 @@ const doc = (spec?.document ?? {}) as {
     securitySchemes?: Record<string, SecuritySchemeLike>;
   };
   security?: SecurityRequirementLike[];
-  servers?: { url?: string }[];
+  servers?: ServerLike[];
 };
 const pathItem = ref ? doc.paths?.[ref.path] : undefined;
 const operation = (
@@ -123,7 +133,13 @@ const model =
         requestBody,
         schemas,
         security,
-        servers: doc.servers ?? [],
+        // An operation's own `servers` override its path item's, which
+        // override the document's.
+        servers: effectiveServers(
+          operation.servers,
+          pathItem?.servers,
+          doc.servers
+        ),
       })
     : null;
 const sample = model ? buildRequest(model, defaultValues(model)) : null;

package/src/components/openapi/PanelTabs.astro

@@ -62,7 +62,9 @@ const TAB_CLASS =
       </div>
       <blume-panel-tabs class="block overflow-hidden rounded-blume border border-border bg-background">
         <div class="flex items-center justify-between gap-2 border-border border-b px-3">
-          <div class="flex flex-wrap gap-4" role="tablist">
+          <div aria-label={heading} class="flex flex-wrap gap-4" role="tablist">
+            {/* Roving tabindex: only the selected tab is in the Tab order, and
+                the arrow keys, Home, and End move between tabs (panel.ts). */}
             {panels.map((panel, index) => (
               <button
                 aria-controls={idFor("panel", panel.key)}
@@ -71,6 +73,7 @@ const TAB_CLASS =
                 data-panel-tab={panel.key}
                 id={idFor("tab", panel.key)}
                 role="tab"
+                tabindex={index === 0 ? "0" : "-1"}
                 type="button"
               >
                 {panel.label}

package/src/components/openapi/Playground.astro

@@ -1,5 +1,6 @@
 ---
 import { stableId } from "../content/tooltip-id.ts";
+import { withBase } from "../islands/base-path.ts";
 
 import { paramKey, type PlaygroundModel } from "./request.ts";
 
@@ -23,6 +24,11 @@ interface Props {
 
 const { model, proxy, slug, operation } = Astro.props;
 
+// The built-in proxy route carries the site `basePath` but, like every
+// internal URL in the spec data, not `deployment.base`; `withBase` adds it
+// and passes an external proxy URL through untouched.
+const proxyUrl = proxy ? withBase(proxy) : undefined;
+
 // `</script>`-proof embedding: `<` only ever occurs inside JSON strings,
 // where the \u escape is equivalent, so a spec description can never close
 // the model script early and inject markup.
@@ -46,7 +52,7 @@ const CHECKBOX_ROW =
 
 <blume-playground
   class="mb-6 block"
-  data-proxy={proxy || undefined}
+  data-proxy={proxyUrl}
   data-storage-key={`blume-playground:${slug}:${operation}`}
 >
   <script
@@ -194,7 +200,7 @@ const CHECKBOX_ROW =
           <div class={GROUP}>
             <div class={GROUP_HEADING}>
               Body
-              <span class="ml-1.5 font-mono normal-case">
+              <span class="ms-1.5 font-mono normal-case">
                 {model.body.contentType}
               </span>
             </div>

package/src/components/openapi/RequestPanel.astro

@@ -2,14 +2,20 @@
 import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
-import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import {
+  responseExample,
+  type SchemaLike,
+  type SpecValue,
+  toJson,
+} from "./helpers.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
 interface ResponseLike {
@@ -38,9 +44,7 @@ const responsePanels = await Promise.all(
       Object.entries(response.content ?? {}).find(([type]) =>
         type.includes("json")
       )?.[1] ?? Object.values(response.content ?? {})[0];
-    const example = media
-      ? (media.example ?? exampleValue(media.schema, schemas))
-      : undefined;
+    const example = media ? responseExample(media, schemas) : undefined;
     const html =
       example === undefined || example === null
         ? null

package/src/components/openapi/SchemaProperty.astro

@@ -3,33 +3,23 @@ import Description from "./Description.astro";
 import {
   constraints,
   isNullable,
-  refName,
   resolveSchema,
   type SchemaLike,
   typeLabel,
 } from "./helpers.ts";
+import { rowExpands, type SchemaRow } from "./schema-tree.ts";
 import SchemaTable from "./SchemaTable.astro";
 
 interface Props {
-  name: string;
-  schema: SchemaLike;
-  required?: boolean;
+  /** One planned row of the parent table (see `schema-tree.ts`). */
+  row: SchemaRow;
   schemas: Record<string, SchemaLike>;
-  seen?: string[];
   expandAll?: boolean;
 }
 
-const {
-  name,
-  schema,
-  required = false,
-  schemas,
-  seen = [],
-  expandAll = false,
-} = Astro.props;
+const { row, schemas, expandAll = false } = Astro.props;
+const { name, schema, required } = row;
 
-const refLabel = typeof schema.$ref === "string" ? refName(schema.$ref) : null;
-const circular = refLabel !== null && seen.includes(refLabel);
 const resolved = resolveSchema(schemas, schema);
 
 const type = typeLabel(schema);
@@ -39,20 +29,9 @@ const nullable = isNullable(resolved);
 const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
 const limits = constraints(resolved);
 
-const types = Array.isArray(resolved.type) ? resolved.type : [resolved.type];
-const isArray = types.includes("array");
-const items = isArray ? resolveSchema(schemas, resolved.items) : null;
-
-const hasObjectShape = (candidate: SchemaLike): boolean =>
-  Boolean(
-    candidate.properties ||
-      candidate.allOf ||
-      candidate.oneOf ||
-      candidate.anyOf ||
-      typeof candidate.$ref === "string"
-  );
-const expandable =
-  !circular && (hasObjectShape(resolved) || Boolean(items && hasObjectShape(items)));
+// Circles and schemas expanded elsewhere in the tree have no disclosure; the
+// type label names them.
+const children = rowExpands(row) ? row.children : undefined;
 ---
 
 {/* The row's vertical scale is 8 / 12 / 16px, and every other reference table copies it. A
@@ -103,17 +82,16 @@ const expandable =
     )
   }
   {
-    expandable && (
+    children && (
       <details class="mt-3" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
           <span class="[details[open]>summary_&]:hidden">Show properties</span>
           <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
-        <div class="mt-3 border-border border-l pl-4">
+        <div class="mt-3 border-border border-s ps-4">
           <SchemaTable
-            schema={schema}
+            node={children.node}
             schemas={schemas}
-            seen={seen}
             expandAll={expandAll}
           />
         </div>

package/src/components/openapi/SchemaTable.astro

@@ -1,86 +1,61 @@
 ---
-import {
-  objectProperties,
-  refName,
-  resolveSchema,
-  type SchemaLike,
-  typeLabel,
-} from "./helpers.ts";
+import type { SchemaLike } from "./helpers.ts";
+import { type SchemaNode, schemaTree } from "./schema-tree.ts";
 import SchemaProperty from "./SchemaProperty.astro";
 
 interface Props {
-  schema: SchemaLike;
+  /** The schema to render, planned here when no `node` is given. */
+  schema?: SchemaLike;
+  /** An already-planned subtree: how nested tables render. */
+  node?: SchemaNode;
   schemas: Record<string, SchemaLike>;
-  /** `$ref` names already on the current branch, to break circular schemas. */
-  seen?: string[];
   expandAll?: boolean;
 }
 
-const { schema, schemas, seen = [], expandAll = false } = Astro.props;
+const { schema = {}, node: planned, schemas, expandAll = false } = Astro.props;
 
-// Track the ref so a self-referential model stops instead of recursing forever.
-const refLabel =
-  typeof schema.$ref === "string" ? refName(schema.$ref) : null;
-const circular = refLabel !== null && seen.includes(refLabel);
-const nextSeen = refLabel ? [...seen, refLabel] : seen;
-const resolved = circular ? schema : resolveSchema(schemas, schema);
-
-const types = Array.isArray(resolved.type) ? resolved.type : [resolved.type];
-const isArray = types.includes("array");
-// Keep array items unresolved so a self-referential item `$ref` stays trackable
-// via `seen` — resolving here would drop the name and loop forever.
-const items = isArray ? (resolved.items ?? null) : null;
-const branches = resolved.oneOf ?? resolved.anyOf ?? null;
-
-const { properties, required } = circular
-  ? { properties: [] as [string, SchemaLike][], required: new Set<string>() }
-  : objectProperties(resolved, schemas);
+// The whole tree is planned once, at the top-level table, so that which named
+// schemas expand is decided for the tree as a whole (see `schema-tree.ts`).
+const node = planned ?? schemaTree(schema, schemas);
 ---
 
 {
-  circular ? (
+  node.kind === "circular" ? (
     <div class="text-muted-foreground text-sm">
-      Circular reference to <code class="text-foreground">{refLabel}</code>.
+      Circular reference to <code class="text-foreground">{node.name}</code>.
     </div>
-  ) : isArray ? (
+  ) : node.kind === "array" ? (
     <div>
       <div class="mb-2 text-muted-foreground text-xs">
-        Array of <code class="text-foreground">{typeLabel(items ?? {})}</code>
+        Array of <code class="text-foreground">{node.itemsLabel}</code>
       </div>
-      {items && (
-        <Astro.self schema={items} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+      {node.items && (
+        <Astro.self node={node.items.node} schemas={schemas} expandAll={expandAll} />
       )}
     </div>
-  ) : branches ? (
+  ) : node.kind === "branches" ? (
     <div class="flex flex-col gap-3">
-      <div class="text-muted-foreground text-xs">
-        {resolved.oneOf ? "One of" : "Any of"}:
-      </div>
-      {branches.map((branch, index) => (
+      <div class="text-muted-foreground text-xs">{node.label}:</div>
+      {node.branches.map((branch) => (
         <div class="rounded-blume border border-border p-3">
           <div class="mb-2 font-medium text-foreground text-xs">
-            {typeLabel(branch) || `Option ${index + 1}`}
+            {branch.label}
           </div>
-          <Astro.self schema={branch} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+          <Astro.self node={branch.slot.node} schemas={schemas} expandAll={expandAll} />
         </div>
       ))}
     </div>
-  ) : properties.length > 0 ? (
+  ) : node.kind === "properties" ? (
     <div class="not-prose">
-      {properties.map(([name, prop]) => (
-        <SchemaProperty
-          name={name}
-          schema={prop}
-          required={required.has(name)}
-          schemas={schemas}
-          seen={nextSeen}
-          expandAll={expandAll}
-        />
+      {node.rows.map((row) => (
+        <SchemaProperty row={row} schemas={schemas} expandAll={expandAll} />
       ))}
     </div>
   ) : (
     <div class="text-muted-foreground text-sm">
-      <code class="text-foreground">{typeLabel(resolved)}</code>
+      <code class="text-foreground">
+        {node.kind === "named" ? node.name : node.label}
+      </code>
     </div>
   )
 }

package/src/components/openapi/helpers.ts

@@ -152,17 +152,31 @@ export const resolveSchema = (
   return schema;
 };
 
-const nonNullTypes = (type: string | string[] | undefined): string[] => {
+const declaredTypeList = (type: string | string[] | undefined): string[] => {
   if (!type) {
     return [];
   }
-  return (Array.isArray(type) ? type : [type]).filter((t) => t !== "null");
+  return Array.isArray(type) ? type : [type];
+};
+
+const nonNullTypes = (type: string | string[] | undefined): string[] =>
+  declaredTypeList(type).filter((t) => t !== "null");
+
+/**
+ * Whether a schema admits only `null`: `{ type: "null" }`, the branch Scalar's
+ * upgrade pairs with a 3.0 `nullable: true` `$ref` (`anyOf: [$ref, { type:
+ * "null" }]`).
+ */
+const isNullType = (schema: SchemaLike): boolean => {
+  const types = declaredTypeList(schema.type);
+  return types.length > 0 && types.every((type) => type === "null");
 };
 
 /**
  * A short, human-readable type label for a schema row. `$ref`s label by name
  * (`Pet`, `Pet[]`) without resolving — which also means circular refs through
- * array items can't recurse forever.
+ * array items can't recurse forever. A `null` member stays out of a union's
+ * label: rows mark it with {@link isNullable}, as they do `type: [T, "null"]`.
  */
 export const typeLabel = (schema: SchemaLike): string => {
   if (isString(schema.$ref)) {
@@ -170,24 +184,42 @@ export const typeLabel = (schema: SchemaLike): string => {
   }
   if (schema.oneOf || schema.anyOf) {
     const branches = schema.oneOf ?? schema.anyOf ?? [];
-    const labels = branches.map((branch) => typeLabel(branch));
+    const members = branches.filter((branch) => !isNullType(branch));
+    if (members.length === 0 && branches.length > 0) {
+      return "null";
+    }
+    const labels = members.map((branch) => typeLabel(branch));
     return [...new Set(labels)].join(" | ") || "any";
   }
   if (schema.allOf) {
     return "object";
   }
   const types = nonNullTypes(schema.type);
+  const arrayLabel = (): string => `${typeLabel(schema.items ?? {})}[]`;
+  if (types.length > 1) {
+    // A 3.1 type array names every type the value may take, not just the first.
+    return types
+      .map((type) => (type === "array" ? arrayLabel() : type))
+      .join(" | ");
+  }
   if (types.includes("array")) {
-    return `${typeLabel(schema.items ?? {})}[]`;
+    return arrayLabel();
+  }
+  if (types.length === 0 && isNullType(schema)) {
+    return "null";
   }
   const base = types[0] ?? (schema.properties ? "object" : "any");
   return schema.format ? `${base}<${schema.format}>` : base;
 };
 
-/** Whether this schema is nullable (3.0 `nullable` or a 3.1 `"null"` in `type`). */
+/**
+ * Whether this schema is nullable: 3.0 `nullable`, a 3.1 `"null"` in `type`,
+ * or a `{ type: "null" }` member of a `oneOf`/`anyOf` union.
+ */
 export const isNullable = (schema: SchemaLike): boolean =>
   schema.nullable === true ||
-  (Array.isArray(schema.type) && schema.type.includes("null"));
+  (Array.isArray(schema.type) && schema.type.includes("null")) ||
+  [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])].some(isNullType);
 
 /** Human-readable validation constraints for a schema, in display order. */
 export const constraints = (schema: SchemaLike): string[] => {
@@ -263,23 +295,26 @@ export const objectProperties = (
  * Build a representative example value for a schema via openapi-sampler
  * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
  * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
- * `readOnly` fields are skipped (these samples illustrate *requests*, and a
- * server-generated field has no place in one), and circular `$ref` chains —
- * which keeping refs intact allows — terminate safely.
+ * and circular `$ref` chains — which keeping refs intact allows — terminate
+ * safely. A request sample skips `readOnly` fields (a server-generated field
+ * has no place in one); a response sample skips `writeOnly` fields (a
+ * password the client sends never comes back) and keeps the `readOnly` ones.
  */
 export const exampleValue = (
   schema: SchemaLike | undefined,
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  direction: "request" | "response" = "request"
 ): SpecValue => {
   if (!schema) {
     return null;
   }
+  const response = direction === "response";
   try {
     // SAFETY: SchemaLike structurally covers the JSONSchema7 fields the
     // sampler reads, and the sampler only ever assembles JSON values.
     return sample(
       schema as Parameters<typeof sample>[0],
-      { quiet: true, skipReadOnly: true },
+      { quiet: true, skipReadOnly: !response, skipWriteOnly: response },
       { components: { schemas } }
     ) as SpecValue;
   } catch {
@@ -289,5 +324,48 @@ export const exampleValue = (
   }
 };
 
+/** Where an author can declare an example: a parameter or a media type. */
+export interface ExampleCarrier {
+  example?: SpecValue;
+  examples?: SpecValue;
+}
+
+const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The example a parameter or media type declares: its `example`, else the
+ * first inline `value` in its `examples` map. Scalar's upgrade moves every
+ * OpenAPI 3.0 and Swagger 2.0 `example` into `examples.default.value`, and
+ * 3.1 authors write that map directly, so reading `example` alone would drop
+ * them all. `undefined` when nothing is declared.
+ */
+export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
+  if (carrier.example !== undefined) {
+    return carrier.example;
+  }
+  const { examples } = carrier;
+  if (!isRecord(examples)) {
+    return undefined;
+  }
+  for (const entry of Object.values(examples)) {
+    if (isRecord(entry) && entry.value !== undefined) {
+      return entry.value;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * A response media type's example for the Response panel: the declared one,
+ * else a sample built for the response direction (`readOnly` kept,
+ * `writeOnly` skipped).
+ */
+export const responseExample = (
+  media: ExampleCarrier & { schema?: SchemaLike },
+  schemas: Record<string, SchemaLike>
+): SpecValue =>
+  declaredExample(media) ?? exampleValue(media.schema, schemas, "response");
+
 /** Pretty-print a JSON value for an example/code block. */
 export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

package/src/components/openapi/message-composer.ts

@@ -199,6 +199,14 @@ export const initComposer = (root: HTMLElement): void => {
 
   const client = createWsClient({ onFrame: renderFrame, onState: renderState });
 
+  // A ClientRouter navigation swaps this panel out of the document without
+  // unloading the page, so a live socket would stay open behind the next page
+  // — and coming back and connecting again would open a second one. Every
+  // swap replaces the panel, so the first one closes the socket for good.
+  document.addEventListener("astro:before-swap", () => client.disconnect(), {
+    once: true,
+  });
+
   connectButton?.addEventListener("click", () => {
     if (validatePayload().length > 0) {
       return;

package/src/components/openapi/message-model.ts

@@ -2,6 +2,7 @@ import type {
   AsyncApiAction,
   AsyncApiServerObject,
 } from "../../openapi/asyncapi.ts";
+import { withServerDefaults } from "../../openapi/model.ts";
 import type { AsyncApiMessageLike, NamedMessage } from "./async.ts";
 import { payloadSchema } from "./async.ts";
 import { exampleValue, toJson } from "./helpers.ts";
@@ -78,9 +79,18 @@ const messagePayload = (
 /**
  * A server's base URL for the picker. Falls back to the bare host when the
  * spec omits `protocol` — a label is a label, and the snippet builders read
- * the server object itself rather than this string.
+ * the server object itself rather than this string. Server variables in the
+ * host and pathname (`{env}.events.example.com`) resolve to their declared
+ * defaults, in the label and in the object the samples and connect URL read.
  */
-const serverOption = (server: AsyncApiServerObject): MessageServerOption => {
+const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
+  const server = { ...spec };
+  if (spec.host !== undefined) {
+    server.host = withServerDefaults(spec.host, spec.variables);
+  }
+  if (spec.pathname !== undefined) {
+    server.pathname = withServerDefaults(spec.pathname, spec.variables);
+  }
   const host = `${server.host ?? ""}${server.pathname ?? ""}`;
   return {
     label: server.protocol ? `${server.protocol}://${host}` : host,

package/src/components/openapi/message.ts

@@ -40,7 +40,10 @@ export interface MessagePayload {
 export interface MessageServerOption {
   /** `protocol://host+pathname` — what the reader picks between. */
   label: string;
-  /** The spec server, verbatim; the snippet builders read host/pathname/protocol. */
+  /**
+   * The spec server with its host/pathname variables at their defaults; the
+   * snippet builders read host/pathname/protocol.
+   */
   server: AsyncApiServerObject;
 }