@shortlink-org/portolan 0.2.1 → 0.2.2

package/src/flow/StepRail.tsx

@@ -2,6 +2,7 @@ import { useEffect, useId, useRef } from "react";
 import { Link } from "react-router";
 import { LayoutGroup, m, transitions } from "../lib/motion";
 import {
+  AlertCircle,
   ArrowRight,
   ChevronDown,
   ChevronRight,
@@ -13,13 +14,11 @@ import { STATUSES } from "../catalog";
 import { contextName, ctxStyle } from "../lib/context-color";
 import { paths } from "../routes";
 import { statusVar } from "../components/primitives";
-import { railRows } from "./chapters";
+import { railRows, stepTitle } from "./chapters";
 import type { Chapter, ChapterGroup } from "./chapters";
 import type { Continuation } from "./continues";
 import type { OutlineFrame, OutlineStep } from "./outline";
 
-
-
 /**
  * A chapter header. The one row on the rail that is a control rather than a
  * reading: it folds its own steps away and nothing else — the canvas keeps
@@ -68,7 +67,10 @@ function ChapterRow({
           {chapter.kind}
         </span>
       )}
-      <span className="mono min-w-0 flex-1 truncate text-ink" title={chapter.title}>
+      <span
+        className="mono min-w-0 flex-1 truncate text-ink"
+        title={chapter.title}
+      >
         {chapter.title}
       </span>
       {/* The contexts this episode touches, as colour and nothing else: the
@@ -89,7 +91,11 @@ function ChapterRow({
       <span className="mono flex shrink-0 items-center gap-1 text-muted">
         {STATUSES.filter((status) => chapter.status[status] > 0).map(
           (status) => (
-            <span key={status} className="flex items-center gap-0.5" title={status}>
+            <span
+              key={status}
+              className="flex items-center gap-0.5"
+              title={status}
+            >
               <span
                 aria-hidden
                 className="size-1.5 rounded-[1px]"
@@ -168,7 +174,9 @@ function CrossChip({ step, context }: { step: Step; context: string | null }) {
   return (
     <span
       className="chip shrink-0 ctx"
-      style={context ? ctxStyle(context) : { borderColor: "var(--border-strong)" }}
+      style={
+        context ? ctxStyle(context) : { borderColor: "var(--border-strong)" }
+      }
       title={`crosses into ${label}`}
     >
       → {label}
@@ -202,6 +210,7 @@ function StepRow({
   const { step, number, depth, hidden, offPath, offStatus } = row;
   const self = step.from === step.to;
   const crosses = crossContext !== undefined;
+  const errorResponse = step.http?.outcome === "error";
   return (
     <div
       onMouseEnter={() => onHover(step.id)}
@@ -226,8 +235,11 @@ function StepRow({
         style={{
           borderLeftWidth: 2,
           borderLeftStyle: "solid",
-          borderLeftColor: "transparent",
+          borderLeftColor: errorResponse
+            ? "var(--response-error)"
+            : "transparent",
           paddingLeft: 8 + depth * 10,
+          background: errorResponse ? "var(--response-error-bg)" : undefined,
         }}
         aria-current={active ? "true" : undefined}
       >
@@ -251,14 +263,17 @@ function StepRow({
                 a character. Both sit on their content and the answer, weighted
                 to give way ten times faster, is the one that loses. */}
             <span
-              className="min-w-0 truncate text-ink"
-              title={step.label ?? step.ref ?? step.kind}
+              className="min-w-0 truncate"
+              style={{
+                color: errorResponse ? "var(--response-error)" : "var(--fg)",
+              }}
+              title={stepTitle(step)}
             >
-              {step.label ?? step.ref ?? step.kind}
+              {stepTitle(step)}
             </span>
-            {/* The reply is not a step of its own - it is the far end of this
-                one - so it is read on the same line, and only where a contract
-                says what comes back. */}
+            {/* A standalone call keeps its contract answer on this line. Once
+                composition proves the nested return, the answer becomes its
+                own response step and is omitted from this map. */}
             {/* Only where there is room for it: two truncated halves read
                 worse than one whole label, so on a rail dragged narrow the
                 answer steps aside and the step's own panel still says it. */}
@@ -291,6 +306,14 @@ function StepRow({
         {full ? (
           <span className="mono shrink-0 text-muted">{step.kind}</span>
         ) : null}
+        {errorResponse ? (
+          <AlertCircle
+            size={12}
+            aria-label="error response"
+            className="mt-0.5 shrink-0"
+            style={{ color: "var(--response-error)" }}
+          />
+        ) : null}
         {crosses ? <CrossChip step={step} context={crossContext} /> : null}
         {hidden ? (
           <span

package/src/flow/answers-response.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+
+import { buildIndex } from "../catalog";
+import type { Catalog, Flow } from "../catalog";
+import { flowAnswers, stepAnswer } from "./answers";
+
+describe("explicit flow responses", () => {
+  it("moves the contract answer off a request that has a response step", () => {
+    const flow: Flow = {
+      id: "flow.get-book",
+      slug: "get-book",
+      name: "Get book",
+      summary: "",
+      owner: "demo",
+      participants: [
+        { id: "demo.api", kind: "service", context: "demo" },
+        { id: "demo.book", kind: "service", context: "demo" },
+      ],
+      steps: [
+        {
+          type: "step",
+          id: "request",
+          from: "demo.api",
+          to: "demo.book",
+          kind: "rpc",
+          ref: "book.v1.Book/Get",
+          label: "Get",
+          status: "declared",
+        },
+        {
+          type: "step",
+          id: "response",
+          from: "demo.book",
+          to: "demo.api",
+          kind: "response",
+          label: "GetResponse",
+          status: "declared",
+          replyTo: "request",
+        },
+      ],
+    };
+    const catalog: Catalog = {
+      generatedAt: "2026-09-09T00:00:00Z",
+      commit: "0000000",
+      contexts: [
+        {
+          id: "demo",
+          slug: "demo",
+          name: "Demo",
+          summary: "",
+          services: [
+            {
+              id: "demo.api",
+              slug: "api",
+              name: "API",
+              repo: "",
+              path: "",
+              readme: "",
+              provides: [],
+              consumes: [],
+              aggregates: [],
+            },
+            {
+              id: "demo.book",
+              slug: "book",
+              name: "Book",
+              repo: "",
+              path: "",
+              readme: "",
+              provides: [
+                {
+                  id: "book.v1.Book",
+                  source: "book.proto",
+                  methods: [
+                    {
+                      name: "Get",
+                      request: "GetRequest",
+                      response: "GetResponse",
+                    },
+                  ],
+                },
+              ],
+              consumes: [],
+              aggregates: [],
+            },
+          ],
+        },
+      ],
+      defs: {},
+      flows: [flow],
+      adrs: [],
+    };
+    const index = buildIndex(catalog);
+    const request = flow.steps[0];
+    if (request?.type !== "step") throw new Error("missing request");
+
+    expect(stepAnswer(index, request)).toBe("GetResponse");
+    expect(flowAnswers(index, flow).has(request.id)).toBe(false);
+  });
+});

package/src/flow/answers.ts

@@ -1,12 +1,9 @@
 // What comes back from a call, when a contract says.
 //
-// The catalog records hops - a call was made, an event was published - and
-// never a reply: a reply is not a second thing that happened, it is the far end
-// of the same one. But a reader of a sequence still wants to see what the far
-// end hands over, and for an rpc the answer is already written down twice over:
-// in the proto that declares the method, and in the OpenAPI document that
-// declares the operation. So it is looked up rather than recorded, and a step
-// whose method nobody in the catalog provides simply has no answer to draw.
+// The catalog's source facts are hops - a call was made, an event was
+// published. Composition may synthesize a response when a proven synchronous
+// continuation returns, but standalone calls still need their answer read from
+// the contract and shown on the request itself.
 //
 // Only an rpc has one. A `call` lands inside a service - a repository, a
 // queryset - which no interface in the catalog describes; an event is a
@@ -47,10 +44,16 @@ export function stepAnswer(index: CatalogIndex, step: Step): string | undefined
   return methodOf(index, step)?.response || undefined;
 }
 
-/** Every step of a flow that has one, by step id. */
+/** Every request without an explicit response step that has an answer. */
 export function flowAnswers(index: CatalogIndex, flow: Flow): Map<string, string> {
   const out = new Map<string, string>();
+  const explicit = new Set(
+    walkSteps(flow.steps)
+      .filter((step) => step.kind === "response" && step.replyTo)
+      .map((step) => step.replyTo as string),
+  );
   for (const step of walkSteps(flow.steps)) {
+    if (explicit.has(step.id)) continue;
     const answer = stepAnswer(index, step);
     if (answer) out.set(step.id, answer);
   }

package/src/flow/chapters.ts

@@ -21,6 +21,7 @@
 import type { Flow, FlowNode, Status, Step } from "../catalog";
 import { walkSteps } from "../catalog";
 import { contextResolver } from "./cross-context";
+import { stepLabel } from "./labels";
 import type { OutlineRow } from "./outline";
 
 export type ChapterKind = "alt" | "par" | "loop" | "steps";
@@ -55,7 +56,7 @@ export interface ChapterGroup {
 
 /** What a step is called when it has to name something. */
 export function stepTitle(step: Step): string {
-  return step.label ?? step.ref ?? step.kind;
+  return stepLabel(step);
 }
 
 const NO_STATUS: Record<Status, number> = {

package/src/flow/labels.ts

@@ -0,0 +1,10 @@
+import type { Step } from "../catalog";
+
+/** The message a reader sees everywhere a flow step is listed or drawn. */
+export function stepLabel(step: Step): string {
+  const access = step.storeAccess;
+  if (access?.operation && access.keyspace) {
+    return `${access.operation.toUpperCase()} ${access.keyspace}`;
+  }
+  return step.label ?? step.ref ?? step.kind;
+}

package/src/flow/mermaid.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
+import type { Flow } from "../catalog";
 import { catalog, index } from "../data";
 import { flowAnswers } from "./answers";
 import { flowMermaid } from "./mermaid";
@@ -15,8 +16,91 @@ function generated(slug: string): string {
 describe("flowMermaid", () => {
   // The Go generator and this port draw the same diagram, or one of them is
   // wrong; the generated pages are the record of what the Go one drew.
-  it.each(catalog.flows.map((f) => f.slug))("draws %s as gen-markdown does", (slug) => {
-    const flow = catalog.flows.find((f) => f.slug === slug)!;
-    expect(flowMermaid(flow, flowAnswers(index, flow))).toBe(generated(slug));
+  it.each(catalog.flows.map((f) => f.slug))(
+    "draws %s as gen-markdown does",
+    (slug) => {
+      const flow = catalog.flows.find((f) => f.slug === slug)!;
+      expect(flowMermaid(flow, flowAnswers(index, flow))).toBe(generated(slug));
+    },
+  );
+
+  it("draws a synthesized response as a dashed reverse message", () => {
+    const flow: Flow = {
+      id: "flow.reply",
+      slug: "reply",
+      name: "Reply",
+      summary: "",
+      owner: "shop",
+      participants: [
+        { id: "client", kind: "actor", context: null },
+        { id: "shop.api", kind: "service", context: "shop" },
+      ],
+      steps: [
+        {
+          type: "step",
+          id: "request",
+          from: "client",
+          to: "shop.api",
+          kind: "rpc",
+          label: "GET /book",
+          status: "declared",
+        },
+        {
+          type: "step",
+          id: "response",
+          from: "shop.api",
+          to: "client",
+          kind: "response",
+          label: "HTTP response",
+          status: "declared",
+          replyTo: "request",
+        },
+      ],
+    };
+
+    expect(flowMermaid(flow)).toContain(
+      "p0->>p1: GET /book\n    p1-->>p0: HTTP response",
+    );
+
+    const response = flow.steps[1];
+    if (response?.type !== "step") throw new Error("response fixture missing");
+    response.http = { status: 500, outcome: "error" };
+    response.label = "500 · Error";
+    expect(flowMermaid(flow)).toContain(
+      "rect rgba(183, 100, 107, 0.12)\n        p1-->>p0: 500 · Error\n    end",
+    );
+  });
+
+  it("labels a resolved Redis call by its concrete operation and key", () => {
+    const flow: Flow = {
+      id: "flow.redis",
+      slug: "redis",
+      name: "Redis",
+      summary: "",
+      owner: "shop",
+      participants: [
+        { id: "shop.api", kind: "service", context: "shop" },
+        { id: "shop.redis", kind: "store", context: "shop" },
+      ],
+      steps: [
+        {
+          type: "step",
+          id: "read",
+          from: "shop.api",
+          to: "shop.redis",
+          kind: "call",
+          label: "Get",
+          status: "verified",
+          storeAccess: {
+            store: "shop.redis",
+            method: "Store.Get",
+            operation: "read",
+            keyspace: "{id}",
+          },
+        },
+      ],
+    };
+
+    expect(flowMermaid(flow)).toContain("p0->>p1: READ {id}");
   });
 });

package/src/flow/mermaid.ts

@@ -7,6 +7,7 @@
 // the catalog has a dotted service id.
 
 import type { Flow, FlowNode, Step } from "../catalog";
+import { stepLabel } from "./labels";
 
 /**
  * `answers` is what each step's callee hands back, by step id - see
@@ -42,17 +43,28 @@ function emit(
   for (const node of nodes) {
     switch (node.type) {
       case "step": {
-        // An event is drawn with the async arrow. A reader who cannot tell a
-        // call from a publication is reading a different flow.
-        const arrow = node.kind === "event" ? "-)" : "->>";
-        // The reply rides on the hop's own label rather than coming back as a
-        // second message: `autonumber` counts messages, and the numbers here
-        // are the numbers of the step list beside the diagram.
-        out.push(`${indent}${of(node.from)}${arrow}${of(node.to)}: ${text(labelWithAnswer(node, answers))}`);
+        // Events use the async arrow; synthesized responses use the standard
+        // dashed return. A reader can now distinguish all three directions.
+        const arrow =
+          node.kind === "response"
+            ? "-->>"
+            : node.kind === "event"
+              ? "-)"
+              : "->>";
+        const message = `${of(node.from)}${arrow}${of(node.to)}: ${text(labelWithAnswer(node, answers))}`;
+        if (node.http?.outcome === "error") {
+          out.push(`${indent}rect rgba(183, 100, 107, 0.12)`);
+          out.push(`${indent}    ${message}`);
+          out.push(`${indent}end`);
+        } else {
+          out.push(`${indent}${message}`);
+        }
         break;
       }
       case "parallel": {
-        out.push(`${indent}par ${text(node.title?.trim() ? node.title : "in parallel")}`);
+        out.push(
+          `${indent}par ${text(node.title?.trim() ? node.title : "in parallel")}`,
+        );
         node.branches.forEach((branch, i) => {
           if (i > 0) out.push(`${indent}and`);
           emit(branch, of, depth + 1, out, answers);
@@ -62,14 +74,18 @@ function emit(
       }
       case "alt": {
         node.branches.forEach((branch, i) => {
-          out.push(`${indent}${i === 0 ? "alt " : "else "}${text(branch.title)}`);
+          out.push(
+            `${indent}${i === 0 ? "alt " : "else "}${text(branch.title)}`,
+          );
           emit(branch.steps, of, depth + 1, out, answers);
           // A branch that ends the flow has to say so inside the diagram, or
           // the steps drawn after the alt read as if they follow it too.
           if (branch.terminal) {
             const last = lastParticipant(branch.steps);
             if (last)
-              out.push(`${"    ".repeat(depth + 1)}Note over ${of(last)}: flow ends here`);
+              out.push(
+                `${"    ".repeat(depth + 1)}Note over ${of(last)}: flow ends here`,
+              );
           }
         });
         out.push(`${indent}end`);
@@ -85,10 +101,6 @@ function emit(
   }
 }
 
-function stepLabel(step: Step): string {
-  return step.label || step.ref || step.kind;
-}
-
 function lastParticipant(nodes: FlowNode[]): string {
   for (let i = nodes.length - 1; i >= 0; i--) {
     const node = nodes[i]!;

package/src/index.css

@@ -54,6 +54,10 @@
   /* Domain events are the loudest leaf in the tree. Amber, but a step darker
      than amber-600 so 12px mono still clears contrast on white. */
   --kind-event: #b45309;
+  /* Error paths should be unmistakable without turning the diagram into an
+     alarm panel: dusty rose on a very pale wash. */
+  --response-error: #b7646b;
+  --response-error-bg: #faedef;
 
   /* GitHub paints `[!IMPORTANT]` purple. Purple already exists in the context
      ramp, where it means "this context"; the alert gets a name of its own so
@@ -170,6 +174,8 @@
   --status-unresolved: #ff6b63;
 
   --kind-event: #e8a33d;
+  --response-error: #d98288;
+  --response-error-bg: #2a1c20;
 
   --alert-important: #b98cf0;
 
@@ -616,6 +622,9 @@
       border-color var(--dur-micro) var(--ease-out),
       box-shadow var(--dur-panel) var(--ease-out);
   }
+  .product-primary {
+    cursor: pointer;
+  }
   :root:not(.dark) :is(.landing-primary, .product-primary) {
     color: var(--product-action-ink);
     border-color: color-mix(in srgb, var(--product-action) 52%, var(--border));
@@ -1015,6 +1024,129 @@
     font-size: var(--text-meta);
   }
 
+  /* Cats mark rare, positive empty states and milestones rather than routine gaps. */
+  .cat-illustration {
+    display: block;
+    object-fit: contain;
+    pointer-events: none;
+    user-select: none;
+    filter: drop-shadow(0 12px 18px rgb(10 18 26 / 10%));
+  }
+
+  .cat-empty-state {
+    @apply glow grid items-center gap-5 rounded-card border border-dashed border-line-strong px-5 py-4;
+    grid-template-columns: 180px minmax(0, 1fr);
+  }
+
+  .cat-empty-illustration {
+    width: 180px;
+    height: 126px;
+    justify-self: center;
+  }
+
+  .cat-onboarding-illustration {
+    width: 104px;
+    height: 82px;
+    margin-block: -10px;
+  }
+
+  .cat-search-empty {
+    @apply glow flex items-center justify-center gap-4 px-4 py-4;
+    min-height: 104px;
+  }
+
+  .cat-search-illustration {
+    width: 92px;
+    height: 68px;
+  }
+
+  .cat-trial-illustration {
+    width: 120px;
+    height: 88px;
+    margin-block: -8px;
+    justify-self: center;
+  }
+
+  @media (max-width: 520px) {
+    .cat-empty-state {
+      grid-template-columns: 104px minmax(0, 1fr);
+      gap: 16px;
+      padding: 16px;
+    }
+
+    .cat-empty-illustration {
+      width: 104px;
+      height: 92px;
+    }
+
+    .cat-onboarding-illustration {
+      width: 76px;
+      height: 66px;
+    }
+
+    .cat-trial-illustration {
+      width: 90px;
+      height: 72px;
+    }
+  }
+
+  /* The 404 is a small editorial moment inside the catalog rather than a
+     centred error dialog. Copy keeps a readable left edge; the transparent
+     explorer sits quietly beside it. */
+  .not-found-page {
+    @apply glow flex h-full min-h-0 items-center justify-center overflow-y-auto p-gutter;
+  }
+  .not-found-state {
+    display: grid;
+    grid-template-columns: minmax(260px, 0.9fr) minmax(360px, 1fr);
+    align-items: center;
+    gap: clamp(32px, 6vw, 72px);
+    width: min(100%, 980px);
+    margin: auto;
+  }
+  .not-found-copy {
+    max-width: 480px;
+  }
+  .not-found-art {
+    position: relative;
+    aspect-ratio: 4 / 3;
+  }
+  .not-found-cat {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+    user-select: none;
+    filter: drop-shadow(0 18px 22px rgb(10 18 26 / 0.12));
+  }
+  .not-found-request {
+    @apply grid grid-cols-[auto_minmax(0,1fr)] items-center gap-3 rounded-control border border-line bg-surface px-3 py-2;
+  }
+  .not-found-key {
+    margin-left: 2px;
+    padding: 0 4px;
+    border: 1px solid color-mix(in srgb, var(--fg) 22%, transparent);
+    border-radius: 4px;
+    color: inherit;
+  }
+
+  @media (max-width: 760px) {
+    .not-found-page {
+      align-items: flex-start;
+    }
+    .not-found-state {
+      grid-template-columns: 1fr;
+      gap: 8px;
+      width: min(100%, 520px);
+    }
+    .not-found-art {
+      width: min(88%, 380px);
+      margin-inline: auto;
+    }
+    .not-found-copy {
+      max-width: none;
+    }
+  }
+
   /* ---------------------------------------------------------------------
      Identifiers. Every id, path and type name in the app is an <Ident>, and
      every <Ident> is this button: it looks like text until the pointer is on

package/src/landing/LandingPage.tsx

@@ -30,8 +30,12 @@ import { DraggableReveal } from "./DraggableReveal";
 import { heroColumn, heroLine, Reveal } from "./motion";
 import { ProductFrame } from "./ProductFrame";
 import { ProductTour } from "./ProductTour";
+import {
+  PRODUCT_LICENSE,
+  PRODUCT_README,
+  PRODUCT_REPOSITORY,
+} from "../lib/product";
 
-const REPOSITORY = "https://github.com/shortlink-org/portolan";
 const EXAMPLE_DOCS = "https://shortlink-org.github.io/portolan/docs/example";
 const exampleTo = catalogTo(paths.overview());
 
@@ -86,7 +90,7 @@ function Header() {
             {theme === "dark" ? <Sun size={15} /> : <Moon size={15} />}
           </button>
           <a
-            href={REPOSITORY}
+            href={PRODUCT_REPOSITORY}
             className="tbtn hidden sm:flex"
             target="_blank"
             rel="noreferrer"
@@ -362,7 +366,7 @@ export function LandingPage() {
             <div className="shrink-0">
               <div className="mono text-faint">BUILT-IN INPUTS</div>
               <a
-                href={`${REPOSITORY}#plugins`}
+                href={`${PRODUCT_REPOSITORY}#plugins`}
                 target="_blank"
                 rel="noreferrer"
                 className="mt-1 inline-flex items-center gap-1 text-sm text-accent hover:underline"
@@ -648,7 +652,7 @@ export function LandingPage() {
                   Open the example <ArrowRight size={15} />
                 </Link>
                 <a
-                  href={`${REPOSITORY}#use-it-in-your-project`}
+                  href={`${PRODUCT_REPOSITORY}#use-it-in-your-project`}
                   className="tbtn px-4 py-2.5 text-ink"
                   target="_blank"
                   rel="noreferrer"
@@ -720,7 +724,7 @@ export function LandingPage() {
                 Explore example catalog <ArrowRight size={15} />
               </Link>
               <a
-                href={REPOSITORY}
+                href={PRODUCT_REPOSITORY}
                 target="_blank"
                 rel="noreferrer"
                 className="tbtn px-4 py-2.5 text-ink"
@@ -737,16 +741,16 @@ export function LandingPage() {
           <Wordmark />
           <span className="sm:ml-3">Architecture from code and evidence.</span>
           <div className="flex gap-5 sm:ml-auto">
-            <a className="hover:text-ink" href={`${REPOSITORY}#readme`}>
+            <a className="hover:text-ink" href={PRODUCT_README}>
               Docs
             </a>
             <a
               className="hover:text-ink"
-              href={`${REPOSITORY}/blob/main/LICENSE`}
+              href={PRODUCT_LICENSE}
             >
               MIT License
             </a>
-            <a className="hover:text-ink" href={REPOSITORY}>
+            <a className="hover:text-ink" href={PRODUCT_REPOSITORY}>
               GitHub
             </a>
           </div>