@revenexx/studio-integrations 0.7.0 → 1.0.0

package/dist/runtime/components/Integrations/NodeInspector.vue

@@ -1,7 +1,8 @@
 <script setup>
 import { computed, nextTick, onMounted, provide, ref, watch } from "vue";
-import { AddCircle as Plus, TrashBinMinimalistic as TrashBin, Copy } from "#solar-icons";
-import { ChevronDown, ChevronLeft, ChevronRight, Clock, Database, MessageSquareText, Play, Search, Webhook, X, Zap } from "lucide-vue-next";
+import { AddCircle as Plus, Copy, Magnifier as Search, TrashBinMinimalistic as TrashBin } from "#solar-icons";
+import { triggerGlyph as glyphForTrigger } from "../../data/triggerGlyphs";
+import { ChevronDown, ChevronLeft, ChevronRight, Database, MessageSquareText, X } from "lucide-vue-next";
 import { toast } from "vue-sonner";
 import {
   Button,
@@ -27,9 +28,10 @@ import {
   ToggleGroupItem
 } from "@revenexx/studio";
 import EventTypeCombobox from "./EventTypeCombobox.vue";
-import { findManifest, nodeCategoryLabel } from "../../data/integrationNodeCatalog";
+import { findManifest, nodeCategoryLabel, isVersionExecutable, newestExecutableVersion } from "../../data/integrationNodeCatalog";
 import {
   collectUpstreamNodes,
+  inputPortsForManifest,
   nodeOutputExpr,
   portsForNode,
   triggerPayloadExpr,
@@ -87,14 +89,21 @@ const manifest = computed(() => {
   const wn = draftNode.value;
   return wn ? findManifest(wn.nodeSlug, wn.nodeVersion) : null;
 });
-const TRIGGER_GLYPHS = { manual: Play, schedule: Clock, webhook: Webhook, event: Zap };
+const versionExecutable = computed(() => {
+  const wn = draftNode.value;
+  return wn ? isVersionExecutable(wn.nodeSlug, wn.nodeVersion) : true;
+});
+const readyVersion = computed(() => {
+  const wn = draftNode.value;
+  return wn ? newestExecutableVersion(wn.nodeSlug) : null;
+});
 const TRIGGER_LABELS = computed(() => ({
   manual: t("integration.nodeInspector.trigger.type.manual"),
   schedule: t("integration.nodeInspector.trigger.type.schedule"),
   webhook: t("integration.nodeInspector.trigger.type.webhook"),
   event: t("integration.nodeInspector.trigger.type.event")
 }));
-const triggerGlyph = computed(() => TRIGGER_GLYPHS[draftTrigger.value?.type ?? "manual"]);
+const triggerGlyph = computed(() => glyphForTrigger(draftTrigger.value?.type));
 const namePlaceholder = computed(() => {
   if (draftNode.value) return resolveLocalized(manifest.value?.name) || draftNode.value.nodeSlug;
   return t("integration.nodeInspector.trigger.placeholder", { type: TRIGGER_LABELS.value[draftTrigger.value?.type ?? "manual"] });
@@ -115,6 +124,7 @@ const nameValue = computed(() => {
   const name = draft.value.name;
   return resolveDisplayName(name);
 });
+const dialogTitle = computed(() => t("integration.nodeInspector.dialogTitle", { name: nameValue.value || namePlaceholder.value }));
 function writeName(name) {
   draft.value = { ...draft.value, name };
 }
@@ -759,6 +769,7 @@ function navigate(offset) {
   emit("navigate", target);
 }
 const outputView = ref("schema");
+const selfInputs = computed(() => inputPortsForManifest(manifest.value));
 const selfSample = computed(() => draftNode.value ? sampleFor(draftNode.value.id) : void 0);
 const selfPorts = computed(() => draftNode.value ? withSampledFields(portsForNode(draftNode.value, manifest.value, props.dynamicOutputs?.[draftNode.value.id]), selfSample.value) : []);
 const selfSampleJson = computed(() => selfSample.value ? JSON.stringify(selfSample.value, null, 2) : "");
@@ -867,6 +878,11 @@ async function runTestStep() {
   <!-- Fills the editor's near-fullscreen config lightbox; the Dialog owns
        width/height, border and the close control. -->
   <div class="flex min-h-0 flex-1 flex-col bg-white">
+    <!-- The dialog's accessible name. Not drawn: the header below says the same
+         thing in the name field and the line under it, and says it better. -->
+    <DialogTitle class="sr-only">
+      {{ dialogTitle }}
+    </DialogTitle>
     <!-- Header -->
     <div class="flex shrink-0 items-center gap-3 border-b border-black/[0.06] px-4 py-3">
       <div class="flex size-9 shrink-0 items-center justify-center rounded-md border border-black/[0.06] bg-slate-50 text-slate-600">
@@ -1032,6 +1048,36 @@ async function runTestStep() {
           <p class="mt-0.5 text-xs leading-snug text-muted-foreground">
             {{ t("integration.nodeInspector.input.description") }}
           </p>
+          <!-- What this node accepts, as opposed to the list below, which is what
+               other nodes offer it. It sits in the header because somebody
+               choosing a value is already reading here, and because the port
+               belongs to the node being configured rather than to any row in the
+               list (AC-20). -->
+          <div v-if="isNode && selfInputs.length" class="mt-2 space-y-1 border-t border-black/[0.06] pt-2">
+            <div v-for="p in selfInputs" :key="p.name" class="space-y-0.5">
+              <div class="flex items-baseline gap-1.5">
+                <!-- Not the uppercase treatment the section labels below use, and
+                     that is the point: NODES / TRIGGER / VARIABLES each head a list
+                     of values a click inserts, so they are a series of *sources*.
+                     This heads nothing and is not a source — it is a statement about
+                     the node being configured. Dressed as a fourth member of that
+                     series it told the reader there was a fourth place to take data
+                     from. -->
+                <span
+                  class="text-xs font-medium text-muted-foreground"
+                  :class="selfInputs.length > 1 ? 'font-mono' : ''"
+                >
+                  {{ selfInputs.length > 1 ? `${p.name}:` : t("integration.nodeInspector.input.expects.heading") }}
+                </span>
+                <span class="font-mono text-[10px] text-slate-500">
+                  {{ p.dataType }}<template v-if="p.dataType"> · </template>{{ p.required ? t("integration.nodeInspector.input.expects.required") : t("integration.nodeInspector.input.expects.optional") }}
+                </span>
+              </div>
+              <p v-if="resolveLocalized(p.description)" class="text-xs leading-snug text-muted-foreground">
+                {{ resolveLocalized(p.description) }}
+              </p>
+            </div>
+          </div>
           <div class="relative mt-2">
             <Search :size="12" class="pointer-events-none absolute left-2 top-1/2 -translate-y-1/2 text-muted-foreground" />
             <input
@@ -1098,7 +1144,30 @@ async function runTestStep() {
                   </span>
                 </button>
                 <div v-show="!sectionClosed(s.id)" class="space-y-2 border-t border-black/[0.06] px-2 py-2">
-                <div v-for="p in s.ports" :key="p.name" class="space-y-1 pl-0.5">
+                <!-- These ports belong to an UPSTREAM node, so the sentence is that
+                     node's. On a 300px column it is a tooltip rather than text: the
+                     values below are what this panel is for, and a sentence per port
+                     pushes them out of view. The readable copy is the Output tab
+                     (AC-19).
+
+                     The title hangs on the port's whole block, not on its name row:
+                     that row is only drawn for a node with several ports or a
+                     branch/error one, so a single `default` port — which is most
+                     nodes, No Operation among them — would have had nowhere to carry
+                     it and the tooltip would have been dead in the commonest case.
+
+                     What that buys is uneven, and it is the reason this is a
+                     convenience rather than a promise: each field row carries its own
+                     title (the expression to copy), and a child title wins, so the
+                     sentence is read by resting on the port's name or the space around
+                     its rows rather than on a row itself. Where a reader is owed the
+                     text outright, that is the Output tab. -->
+                <div
+                  v-for="p in s.ports"
+                  :key="p.name"
+                  class="space-y-1 pl-0.5"
+                  :title="resolveLocalized(p.description) || void 0"
+                >
                   <div v-if="s.ports.length > 1 || p.kind !== 'default'" class="flex items-center gap-1.5">
                     <span class="size-1.5 rounded-full" :class="portDotClass(p.kind, p.name)" />
                     <span class="text-[10px] font-medium uppercase tracking-wider text-muted-foreground">{{ p.name }}</span>
@@ -1207,6 +1276,19 @@ async function runTestStep() {
         <!-- Same TabBar as the workflow page — one tab look everywhere. -->
         <TabBar v-model="tab" :tabs="inspectorTabs" class="shrink-0 px-4" />
 
+        <!-- The pinned version has no built code, so nothing here can be tested
+             or resolved. Above the tabs' content rather than inside one of them:
+             the state belongs to the node, not to a tab, and a reader who opens
+             this node on Parameters would otherwise meet the card's mark outside
+             and no word about it inside. Outside the scrolling area so it cannot
+             be scrolled away from. -->
+        <p
+          v-if="isNode && !versionExecutable"
+          class="mx-4 mb-1 shrink-0 rounded-md border border-rose-200 bg-rose-50 px-2.5 py-1.5 text-sm text-rose-700"
+        >
+          {{ readyVersion ? t("integration.nodeInspector.notice.versionNotReady.upgrade", { version: draftNode?.nodeVersion ?? "", ready: readyVersion }) : t("integration.nodeInspector.notice.versionNotReady.none", { version: draftNode?.nodeVersion ?? "" }) }}
+        </p>
+
         <div
           class="min-h-0 flex-1 overflow-y-auto p-4"
           :class="dragActive ? 'chip-drag-live' : ''"
@@ -1654,6 +1736,7 @@ async function runTestStep() {
                 :version="draftNode.nodeVersion"
                 :secret-keys="secretKeys"
                 :static-keys="(manifest.config ?? []).map((f2) => f2.key)"
+                :sibling-fields="manifest.config ?? []"
                 :depth="0"
                 :variables="variables"
                 :upstream-outputs="upstreamOutputs"
@@ -1693,6 +1776,7 @@ async function runTestStep() {
                     :version="draftNode.nodeVersion"
                     :secret-keys="secretKeys"
                     :static-keys="(manifest.config ?? []).map((f2) => f2.key)"
+                    :sibling-fields="manifest.config ?? []"
                     :depth="0"
                     :variables="variables"
                     :upstream-outputs="upstreamOutputs"
@@ -1734,6 +1818,7 @@ async function runTestStep() {
                 :version="draftNode.nodeVersion"
                 :secret-keys="secretKeys"
                 :static-keys="(manifest?.config ?? []).map((f2) => f2.key)"
+                :sibling-fields="manifest?.config ?? []"
                 :depth="0"
                 :variables="variables"
                 :upstream-outputs="upstreamOutputs"
@@ -1878,8 +1963,8 @@ async function runTestStep() {
                 <Button
                   size="sm"
                   class="h-8"
-                  :disabled="testRunning"
-                  :title="t('integration.nodeInspector.output.test.runTitle')"
+                  :disabled="testRunning || !versionExecutable"
+                  :title="versionExecutable ? t('integration.nodeInspector.output.test.runTitle') : void 0"
                   @click="runTestStep"
                 >
                   {{ testRunning ? t("integration.nodeInspector.output.test.running") : t("integration.nodeInspector.output.test.action") }}
@@ -1892,7 +1977,7 @@ async function runTestStep() {
                   {{ testInputOpen ? t("integration.nodeInspector.output.test.hideInput") : t("integration.nodeInspector.output.test.editInput") }}
                 </button>
                 <span class="text-xs text-muted-foreground">
-                  {{ t("integration.nodeInspector.output.test.runHint") }}
+                  {{ versionExecutable ? t("integration.nodeInspector.output.test.runHint") : "" }}
                 </span>
               </div>
               <Textarea
@@ -1999,7 +2084,7 @@ async function runTestStep() {
           {{ t("integration.common.action.cancel") }}
         </Button>
         <Button size="sm" class="h-8" @click="save">
-          {{ t("integration.common.action.save") }}
+          {{ t("integration.nodeInspector.footer.done") }}
         </Button>
       </div>
     </div>

package/dist/runtime/components/Integrations/NodeInspector.vue.d.ts

@@ -28,13 +28,13 @@ type __VLS_Props = {
     refusedFields?: Record<string, string>;
 };
 declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    close: () => any;
     update: (next: WorkflowTrigger | WorkflowNode) => any;
+    close: () => any;
     remove: () => any;
     navigate: (id: string) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onClose?: (() => any) | undefined;
     onUpdate?: ((next: WorkflowTrigger | WorkflowNode) => any) | undefined;
+    onClose?: (() => any) | undefined;
     onRemove?: (() => any) | undefined;
     onNavigate?: ((id: string) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/runtime/components/Integrations/NodeOutputSchema.d.vue.ts

@@ -3,7 +3,8 @@ import type { PortEntry } from '../../data/nodeInputData.js';
  * The ports a node hands downstream, with their declared fields and whatever
  * sample value is known for each.
  *
- * Rendered from one place — the Output tab (specs/node-configuration.md AC-4). It
+ * Rendered from one place — the Output tab (specs/node-configuration.md AC-4,
+ * and AC-19 for the sentences the publisher wrote about a port and its fields). It
  * keeps its own file for readability rather than for reuse: the schema list is
  * a self-contained tree with its own type glyphs and sample formatting, and
  * inlining it would bury the tab's own markup.

package/dist/runtime/components/Integrations/NodeOutputSchema.vue

@@ -1,6 +1,7 @@
 <script setup>
 import { portDotClass } from "../../data/portTone";
-defineProps({
+import { resolveLocalized } from "../../utils/localize";
+const props = defineProps({
   ports: { type: Array, required: true },
   valueAt: { type: Function, required: true }
 });
@@ -16,6 +17,15 @@ const TYPE_GLYPHS = {
 function typeGlyph(dataType) {
   return dataType ? TYPE_GLYPHS[dataType] ?? null : null;
 }
+function portText(p) {
+  return resolveLocalized(p.description);
+}
+function fieldText(f) {
+  return resolveLocalized(f.description);
+}
+function saysNoFields(p) {
+  return !portText(p) || props.valueAt(p.name) !== null;
+}
 </script>
 
 <template>
@@ -25,14 +35,30 @@ function typeGlyph(dataType) {
         <span class="size-1.5 rounded-full" :class="portDotClass(p.kind, p.name)" />
         <span class="text-[10px] font-medium uppercase tracking-wider text-muted-foreground">{{ p.name }}</span>
       </div>
-      <div v-if="p.fields.length" class="space-y-0.5">
-        <div v-for="f in p.fields" :key="f.name" class="flex min-w-0 items-baseline gap-1 font-mono text-[11px]">
-          <span v-if="typeGlyph(f.dataType)" class="shrink-0 font-semibold" :class="typeGlyph(f.dataType).cls">{{ typeGlyph(f.dataType).char }}</span>
-          <span class="shrink-0 text-slate-700">{{ f.name }}</span>
-          <span v-if="valueAt(p.name, f.name) !== null" class="min-w-0 truncate text-slate-400">: {{ valueAt(p.name, f.name) }}</span>
-        </div>
+      <p v-if="portText(p)" class="text-[11px] leading-snug text-muted-foreground">
+        {{ portText(p) }}
+      </p>
+      <!-- Two columns, sized to the widest field rather than split down the
+           middle: `max-content` puts every sentence one gap after the longest
+           name, so short names like `count` do not leave the reader crossing the
+           dialog to find what they mean, and the names still line up with each
+           other. The sample value is capped for the same reason — left free it
+           would widen the column and push the sentences back out. Both cells are
+           always emitted, or a field with nothing to say would slide the next
+           row's name into the sentence column. -->
+      <div v-if="p.fields.length" class="grid grid-cols-[max-content_minmax(0,1fr)] items-baseline gap-x-6 gap-y-0.5">
+        <template v-for="f in p.fields" :key="f.name">
+          <div class="flex min-w-0 items-baseline gap-1 font-mono text-[11px]">
+            <span v-if="typeGlyph(f.dataType)" class="shrink-0 font-semibold" :class="typeGlyph(f.dataType).cls">{{ typeGlyph(f.dataType).char }}</span>
+            <span class="shrink-0 text-slate-700">{{ f.name }}</span>
+            <span v-if="valueAt(p.name, f.name) !== null" class="max-w-56 truncate text-slate-400">: {{ valueAt(p.name, f.name) }}</span>
+          </div>
+          <p class="min-w-0 text-[11px] leading-snug text-muted-foreground">
+            {{ fieldText(f) }}
+          </p>
+        </template>
       </div>
-      <p v-else class="text-[11px] leading-snug text-muted-foreground">
+      <p v-else-if="saysNoFields(p)" class="text-[11px] leading-snug text-muted-foreground">
         {{ t("integration.nodeInspector.output.schema.noFields") }}<template v-if="valueAt(p.name) !== null">{{ t("integration.nodeInspector.output.schema.sampledSuffix") }} <span class="font-mono">{{ valueAt(p.name) }}</span></template>.
       </p>
     </div>

package/dist/runtime/components/Integrations/NodeOutputSchema.vue.d.ts

@@ -3,7 +3,8 @@ import type { PortEntry } from '../../data/nodeInputData.js';
  * The ports a node hands downstream, with their declared fields and whatever
  * sample value is known for each.
  *
- * Rendered from one place — the Output tab (specs/node-configuration.md AC-4). It
+ * Rendered from one place — the Output tab (specs/node-configuration.md AC-4,
+ * and AC-19 for the sentences the publisher wrote about a port and its fields). It
  * keeps its own file for readability rather than for reuse: the schema list is
  * a self-contained tree with its own type glyphs and sample formatting, and
  * inlining it would bury the tab's own markup.

package/dist/runtime/components/Integrations/NodePalette.vue

@@ -1,8 +1,9 @@
 <script setup>
 import { computed, ref, watch } from "vue";
+import { AltArrowLeft as ArrowLeft, Bolt as Zap, Magnifier as Search } from "#solar-icons";
+import { triggerGlyph } from "../../data/triggerGlyphs";
 import * as Lucide from "lucide-vue-next";
 import { INTEGRATION_NODE_CATALOG, NODE_CATEGORIES, TRIGGER_TEMPLATES } from "../../data/integrationNodeCatalog";
-import { nodeIcon } from "../../data/nodeIcons";
 import { resolveLocalized } from "../../utils/localize";
 const { load: loadNodes } = useIntegrationsNodes();
 onMounted(() => {
@@ -13,7 +14,6 @@ const emit = defineEmits(["insert"]);
 const search = ref("");
 const searchInput = ref(null);
 defineExpose({ focusSearch: () => searchInput.value?.focus() });
-const iconFor = nodeIcon;
 const CORE_GROUP_BY_CATEGORY = {
   control: "Flow",
   transform: "Data",
@@ -76,11 +76,14 @@ function isIntegration(m) {
 function makeGroup(label) {
   return { label, children: /* @__PURE__ */ new Map(), leaves: [], count: 0 };
 }
+function isExecutable(m) {
+  return m.__hasBundle !== false;
+}
 const latestManifests = computed(() => {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const m of INTEGRATION_NODE_CATALOG) {
-    if (seen.has(m.slug)) continue;
+    if (seen.has(m.slug) || !isExecutable(m)) continue;
     seen.add(m.slug);
     out.push(m);
   }
@@ -89,6 +92,7 @@ const latestManifests = computed(() => {
 const versionsBySlug = computed(() => {
   const map = /* @__PURE__ */ new Map();
   for (const m of INTEGRATION_NODE_CATALOG) {
+    if (!isExecutable(m)) continue;
     const list = map.get(m.slug);
     if (list) list.push(m);
     else map.set(m.slug, [m]);
@@ -282,14 +286,14 @@ const searching = computed(() => search.value.trim().length > 0);
           :title="t('integration.canvas.palette.action.back')"
           @click="popLevel"
         >
-          <Lucide.ArrowLeft :size="14" />
+          <ArrowLeft :size="14" />
         </button>
         <div class="min-w-0 flex-1 truncate text-mono text-muted-foreground">
           {{ levelTitle }}
         </div>
       </div>
       <div class="relative">
-        <Lucide.Search :size="12" class="absolute left-2 top-1/2 -translate-y-1/2 text-muted-foreground" />
+        <Search :size="12" class="absolute left-2 top-1/2 -translate-y-1/2 text-muted-foreground" />
         <input
           ref="searchInput"
           v-model="search"
@@ -333,7 +337,7 @@ const searching = computed(() => search.value.trim().length > 0);
                 @click="insertTrigger(tpl)"
               >
                 <span class="flex size-6 shrink-0 items-center justify-center rounded-md bg-emerald-100 text-emerald-600">
-                  <component :is="iconFor(tpl.icon)" :size="13" />
+                  <component :is="triggerGlyph(tpl.type)" :size="13" />
                 </span>
                 <div class="min-w-0">
                   <div class="truncate text-sm font-medium">{{ resolveLocalized(tpl.name) }}</div>
@@ -397,7 +401,7 @@ const searching = computed(() => search.value.trim().length > 0);
               @click="insertTrigger(tpl)"
             >
               <span class="flex size-6 shrink-0 items-center justify-center rounded-md bg-emerald-100 text-emerald-600">
-                <component :is="iconFor(tpl.icon)" :size="13" />
+                <component :is="triggerGlyph(tpl.type)" :size="13" />
               </span>
               <div class="min-w-0">
                 <div class="truncate text-sm font-medium">{{ resolveLocalized(tpl.name) }}</div>
@@ -417,7 +421,7 @@ const searching = computed(() => search.value.trim().length > 0);
                 @click="pushPath(['__triggers'])"
               >
                 <span class="flex size-6 shrink-0 items-center justify-center rounded-md bg-slate-100 text-emerald-600/80">
-                  <Lucide.Zap :size="13" />
+                  <Zap :size="13" />
                 </span>
                 <span class="min-w-0 flex-1 truncate text-sm font-medium">{{ t("integration.canvas.palette.group.triggers") }}</span>
                 <span class="text-sm tabular-nums text-muted-foreground">{{ TRIGGER_TEMPLATES.length }}</span>

package/dist/runtime/components/Integrations/StickyNoteView.vue

@@ -100,24 +100,58 @@ function onHoverLeave() {
 }
 const toolbarVisible = computed(() => editable.value && !editing.value && (hovered.value || !!props.selected));
 function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
 function inline(s) {
   return s.replace(/`([^`\n]+)`/g, '<code class="rounded bg-black/[0.07] px-1 py-px font-mono text-[0.85em]">$1</code>').replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer" class="font-medium underline decoration-current/40 underline-offset-2 hover:decoration-current">$1</a>').replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>").replace(/(^|[^*])\*([^*\n]+)\*(?!\*)/g, "$1<em>$2</em>");
 }
+const NOTE_HEADINGS = [
+  { tag: "h2", cls: "m-0 text-base font-semibold" },
+  { tag: "h3", cls: "m-0 text-sm font-semibold" },
+  { tag: "h4", cls: "m-0 text-sm font-medium" }
+];
+const HEADING_RE = /^(#{1,3})\s+(.+)$/;
+const UL_RE = /^[-*]\s+(.+)$/;
+const OL_RE = /^(\d+)\.\s+(.+)$/;
+function renderList(tag, items) {
+  const li = items.map(({ marker, text }) => {
+    const numeric = tag === "ol" ? " tabular-nums" : "";
+    const hidden = tag === "ul" ? ' aria-hidden="true"' : "";
+    const ordinal = tag === "ol" ? ` value="${Number.parseInt(marker, 10)}"` : "";
+    return `<li${ordinal} class="flex gap-1.5"><span${hidden} class="select-none${numeric}">${marker}</span><span class="min-w-0">${text}</span></li>`;
+  }).join("");
+  return `<${tag} role="list" class="m-0 list-none p-0 pl-1">${li}</${tag}>`;
+}
 function renderMarkdownLite(src) {
-  return escapeHtml(src).split("\n").map((line) => {
-    const h = /^(#{1,3})\s+(.+)$/.exec(line);
+  const lines = escapeHtml(src).split("\n");
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    const h = HEADING_RE.exec(line);
     if (h) {
-      const cls = h[1].length === 1 ? "text-base font-semibold" : h[1].length === 2 ? "text-sm font-semibold" : "text-sm font-medium";
-      return `<div class="${cls}">${inline(h[2])}</div>`;
+      const { tag, cls } = NOTE_HEADINGS[(h[1] ?? "#").length - 1] ?? NOTE_HEADINGS[2];
+      out.push(`<${tag} class="${cls}">${inline(h[2] ?? "")}</${tag}>`);
+      i++;
+      continue;
     }
-    const ul = /^[-*]\s+(.+)$/.exec(line);
-    if (ul) return `<div class="flex gap-1.5 pl-1"><span class="select-none">\u2022</span><span class="min-w-0">${inline(ul[1])}</span></div>`;
-    const ol = /^(\d+)\.\s+(.+)$/.exec(line);
-    if (ol) return `<div class="flex gap-1.5 pl-1"><span class="select-none tabular-nums">${ol[1]}.</span><span class="min-w-0">${inline(ol[2])}</span></div>`;
-    return line ? `<div>${inline(line)}</div>` : "<div>&nbsp;</div>";
-  }).join("");
+    const listRe = UL_RE.test(line) ? UL_RE : OL_RE.test(line) ? OL_RE : null;
+    if (listRe) {
+      const tag = listRe === UL_RE ? "ul" : "ol";
+      const items = [];
+      while (i < lines.length) {
+        const m = listRe.exec(lines[i] ?? "");
+        if (!m) break;
+        items.push({ marker: tag === "ul" ? "\u2022" : `${m[1]}.`, text: inline(m[m.length - 1] ?? "") });
+        i++;
+      }
+      out.push(renderList(tag, items));
+      continue;
+    }
+    out.push(line ? `<div>${inline(line)}</div>` : "<div>&nbsp;</div>");
+    i++;
+  }
+  return out.join("");
 }
 const rendered = computed(() => renderMarkdownLite(props.data.sticky.content));
 function onViewMouseDown(e) {

package/dist/runtime/components/Integrations/SurfaceCard.d.vue.ts

@@ -0,0 +1,50 @@
+/**
+ * One shortcut into a surface the *host* provides — Import & Export, the SFTP
+ * server, the event stream, inbound webhooks. None of the four is a page of this
+ * module: they are the cockpit's, and this card is the studio's landing page
+ * pointing at them.
+ *
+ * So the card has two states, and which one it is in is not its own decision:
+ *
+ * - **`available`** — the host has the surface. The card is a link and behaves
+ *   exactly as it did before PO-223.
+ * - **not available** — the card stays on screen, looks the same, and is a button
+ *   that explains where the surface lives instead of leading into a route the host
+ *   does not serve. Before PO-223 it was a link into nothing: in the playground
+ *   and in the standalone dev studio all four led to a 404.
+ *
+ * **Staying on screen is the point**, and it is the call the managed credential
+ * sources already made (`CredentialRevenexxSource.vue`, PO-222): a control that
+ * vanishes leaves nothing to read the explanation from, and the reader cannot tell
+ * a broken feature from one that belongs somewhere else.
+ *
+ * **No `aria-label`, on purpose** — like `TemplateCard`, the card takes its name
+ * from what it shows. The state is carried by the *role*: "Import & Export,
+ * button" instead of "link" is what says to a screen reader that this does not
+ * navigate, and it says it without announcing something no sighted reader can see
+ * (`specs/accessibility.md` AC-1 names the on-screen text as the source of a name).
+ *
+ * Who decides `available`, and why it is the router rather than a guess about the
+ * host, is `docs/host-surfaces.md`.
+ *
+ * The two branches draw the same body twice rather than sharing it: `as-child`
+ * wants a real element as its child, and the alternatives — a wrapper element
+ * around the card, or a second component for eight lines — cost either the grid
+ * layout or a file. **Keep the two bodies identical.**
+ */
+import type { Component } from 'vue';
+type __VLS_Props = {
+    /** What the surface is called, in the reader's language. */
+    label: string;
+    /** One line on what it is for. Shown in both states. */
+    hint: string;
+    icon: Component;
+    /** Where the surface lives in a host that has it. */
+    to: string;
+    /** Whether this host has it. See the comment above; no default on purpose. */
+    available: boolean;
+    /** What the popover says when it does not. */
+    note: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/runtime/components/Integrations/SurfaceCard.vue

@@ -0,0 +1,55 @@
+<script setup>
+import { ArrowRight } from "#solar-icons";
+import { Popover, PopoverContent, PopoverTrigger } from "@revenexx/studio";
+defineProps({
+  label: { type: String, required: true },
+  hint: { type: String, required: true },
+  icon: { type: null, required: true },
+  to: { type: String, required: true },
+  available: { type: Boolean, required: true },
+  note: { type: String, required: true }
+});
+const CARD_CLASS = "group rounded-lg border border-black/[0.06] bg-white p-3 transition hover:border-black/20";
+</script>
+
+<template>
+  <NuxtLink v-if="available" :to="to" :class="CARD_CLASS">
+    <div class="flex items-center gap-2">
+      <span class="flex size-6 items-center justify-center rounded-md bg-slate-100 text-slate-500">
+        <component :is="icon" :size="12" />
+      </span>
+      <span class="min-w-0 flex-1 truncate text-sm font-semibold">{{ label }}</span>
+      <ArrowRight :size="11" class="text-muted-foreground transition-transform group-hover:translate-x-0.5" />
+    </div>
+    <p class="mt-2 text-sm text-muted-foreground">
+      {{ hint }}
+    </p>
+  </NuxtLink>
+
+  <Popover v-else>
+    <PopoverTrigger as-child>
+      <!-- No `id` here: `PopoverTrigger` puts reka-ui's generated `triggerId` on
+           its child and `PopoverContentImpl` points the opened dialog's
+           `aria-labelledby` at exactly that id, so the popover is named by this
+           card. Ours would replace it (reka's `Slot` merges with the child's
+           props winning) and leave the dialog naming nothing. -->
+      <button type="button" :class="[CARD_CLASS, 'w-full text-left']">
+        <div class="flex items-center gap-2">
+          <span class="flex size-6 items-center justify-center rounded-md bg-slate-100 text-slate-500">
+            <component :is="icon" :size="12" />
+          </span>
+          <span class="min-w-0 flex-1 truncate text-sm font-semibold">{{ label }}</span>
+          <ArrowRight :size="11" class="text-muted-foreground transition-transform group-hover:translate-x-0.5" />
+        </div>
+        <p class="mt-2 text-sm text-muted-foreground">
+          {{ hint }}
+        </p>
+      </button>
+    </PopoverTrigger>
+    <PopoverContent align="start" class="w-72 rounded-lg border border-black/[0.06] bg-white p-3 shadow-lg">
+      <p class="text-sm text-muted-foreground">
+        {{ note }}
+      </p>
+    </PopoverContent>
+  </Popover>
+</template>

package/dist/runtime/components/Integrations/SurfaceCard.vue.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One shortcut into a surface the *host* provides — Import & Export, the SFTP
+ * server, the event stream, inbound webhooks. None of the four is a page of this
+ * module: they are the cockpit's, and this card is the studio's landing page
+ * pointing at them.
+ *
+ * So the card has two states, and which one it is in is not its own decision:
+ *
+ * - **`available`** — the host has the surface. The card is a link and behaves
+ *   exactly as it did before PO-223.
+ * - **not available** — the card stays on screen, looks the same, and is a button
+ *   that explains where the surface lives instead of leading into a route the host
+ *   does not serve. Before PO-223 it was a link into nothing: in the playground
+ *   and in the standalone dev studio all four led to a 404.
+ *
+ * **Staying on screen is the point**, and it is the call the managed credential
+ * sources already made (`CredentialRevenexxSource.vue`, PO-222): a control that
+ * vanishes leaves nothing to read the explanation from, and the reader cannot tell
+ * a broken feature from one that belongs somewhere else.
+ *
+ * **No `aria-label`, on purpose** — like `TemplateCard`, the card takes its name
+ * from what it shows. The state is carried by the *role*: "Import & Export,
+ * button" instead of "link" is what says to a screen reader that this does not
+ * navigate, and it says it without announcing something no sighted reader can see
+ * (`specs/accessibility.md` AC-1 names the on-screen text as the source of a name).
+ *
+ * Who decides `available`, and why it is the router rather than a guess about the
+ * host, is `docs/host-surfaces.md`.
+ *
+ * The two branches draw the same body twice rather than sharing it: `as-child`
+ * wants a real element as its child, and the alternatives — a wrapper element
+ * around the card, or a second component for eight lines — cost either the grid
+ * layout or a file. **Keep the two bodies identical.**
+ */
+import type { Component } from 'vue';
+type __VLS_Props = {
+    /** What the surface is called, in the reader's language. */
+    label: string;
+    /** One line on what it is for. Shown in both states. */
+    hint: string;
+    icon: Component;
+    /** Where the surface lives in a host that has it. */
+    to: string;
+    /** Whether this host has it. See the comment above; no default on purpose. */
+    available: boolean;
+    /** What the popover says when it does not. */
+    note: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;