@shortlink-org/portolan 0.2.0 → 0.2.2

package/src/pages/ContextMap.tsx

@@ -12,8 +12,8 @@
 // whose whole claim is that it does not hold opinions.
 
 import { useDocumentTitle } from "../app/title";
-import { useMemo } from "react";
-import { Link } from "react-router";
+import { useMemo, useState } from "react";
+import { Link, useSearchParams } from "react-router";
 import { ArrowRight, ArrowLeftRight, Boxes, Minus } from "lucide-react";
 import { catalog } from "../data";
 import { plural } from "../lib/format";
@@ -437,6 +437,8 @@ function SeparateWays({
 
 export function ContextMap() {
   useDocumentTitle("Context map");
+  const [search, setSearch] = useSearchParams();
+  const [tour, setTour] = useState(() => search.get("tour") === "1");
   const relations = useMemo(() => contextMap(catalog), []);
   const joined = relations.filter(
     (r) => r.dependencies.length > 0 || r.shared.length > 0,
@@ -444,6 +446,12 @@ export function ContextMap() {
   const apart = relations.filter((r) => !joined.includes(r));
   const wired = joined.length;
 
+  if (catalog.contexts.length === 0) {
+    return (
+      <div className="h-full overflow-y-auto p-gutter"><div className="mx-auto mt-[12vh] max-w-2xl rounded-card border border-accent bg-canvas p-6 shadow-xs"><div className="label mb-2">context map</div><h1 className="text-xl font-semibold text-ink">Your architecture will appear here</h1><p className="mt-2 text-muted">Connect one project first. Portolan will turn detected components, APIs and dependencies into the first map without asking you to draw it by hand.</p><div className="mt-5 flex flex-wrap gap-2"><Link to={paths.settingsProjects()} className="product-primary">Connect your first project</Link><Link to={paths.settings()} className="tbtn">See setup steps</Link></div></div></div>
+    );
+  }
+
   return (
     <div className="h-full overflow-y-auto">
       <div className="flex shrink-0 flex-wrap items-center gap-x-3 gap-y-2 border-b px-gutter py-3 border-line">
@@ -482,6 +490,7 @@ export function ContextMap() {
 
       <div className="flex gap-section p-gutter">
         <div className="min-w-0 flex-1">
+          {tour ? <section className="mb-section overflow-hidden rounded-card border border-accent bg-canvas shadow-xs"><div className="flex items-start justify-between gap-3 border-b border-line bg-surface px-card py-3"><div><div className="font-semibold text-ink">Your first map</div><p className="mt-1 text-muted">Three things are enough to start exploring.</p></div><button type="button" className="tbtn" onClick={() => { setTour(false); search.delete("tour"); setSearch(search, { replace: true }); try { localStorage.setItem("portolan.onboarding.map-tour.v1", "seen"); } catch {} }}>Got it</button></div><ol className="grid md:grid-cols-3"><li className="border-b border-line p-card md:border-r md:border-b-0"><span className="label text-accent">1 · contexts</span><p className="mt-1 text-muted">Each large boundary owns a language and responsibility.</p></li><li className="border-b border-line p-card md:border-r md:border-b-0"><span className="label text-accent">2 · components</span><p className="mt-1 text-muted">Click a context to highlight it; double-click to open its components.</p></li><li className="p-card"><span className="label text-accent">3 · evidence</span><p className="mt-1 text-muted">Relations below explain which calls and events created each connection.</p></li></ol></section> : null}
           <section id={MAP_ANCHOR.model}>
             <SectionTitle
               anchor={MAP_ANCHOR.model}

package/src/pages/ContextPage.tsx

@@ -144,22 +144,29 @@ export function ContextPage() {
                   className="card card-tagged stagger-in"
                   style={{ ...staggerStyle(i), ...ctxStyle(context.id) }}
                 >
-                  <div className="flex items-baseline gap-2">
+                  <div className="flex min-w-0 items-baseline gap-2">
                     <Link
                       to={paths.service(context.id, service.slug)}
                       data-nav-item
-                      className="card-link rounded-control font-semibold"
+                      className="card-link min-w-0 truncate rounded-control font-semibold"
                       title={service.name}
                     >
                       {service.name}
                     </Link>
-                    <Ident value={service.id} className="text-muted" />
                     <RowActions
                       copy={service.id}
                       reveal={service.id}
                       label={service.name}
                     />
-                    <span className="chip">{componentKind(service)}</span>
+                  </div>
+                  {/* The id and kind get their own metadata row. Keeping the
+                      kind after the hidden row actions made it overflow the
+                      card before those actions were even visible. */}
+                  <div className="mt-1.5 flex min-w-0 items-center justify-between gap-2">
+                    <span className="min-w-0 overflow-hidden">
+                      <Ident value={service.id} className="block truncate text-muted" />
+                    </span>
+                    <span className="chip shrink-0">{componentKind(service)}</span>
                   </div>
                   {/* Each number is a link into the part of the service page
                       that lists what it counted. */}

package/src/pages/FlowIndex.tsx

@@ -2,7 +2,7 @@ import { useDocumentTitle } from "../app/title";
 import { useMemo, useState } from "react";
 import { Link, useSearchParams } from "react-router";
 import { ArrowUpDown, X } from "lucide-react";
-import { CATALOG_PATH, catalog } from "../data";
+import { catalog } from "../data";
 import { allRepos, flowContexts, walkSteps } from "../catalog";
 import { FLOW_HEALTH_NOTE, flowHealth, flowOwner, statusCounts } from "../lib/flow-tree";
 import type { FlowHealth } from "../lib/flow-tree";
@@ -15,9 +15,10 @@ import { middleTruncate } from "../lib/format";
 import { staggerStyle } from "../lib/motion";
 import { Ident } from "../components/Ident";
 import { RowActions } from "../components/RowActions";
-import { Blank, Empty } from "../components/PageHeader";
+import { CapabilityEmpty, Empty } from "../components/PageHeader";
 import { ContextPill } from "../components/primitives";
 import { FlowTrigger } from "../components/FlowTrigger";
+import { paths } from "../routes";
 
 type Sort = "contexts" | "name" | "steps" | "health";
 
@@ -189,11 +190,19 @@ export function FlowIndex() {
 
       {bare ? (
         <div className="mt-section">
-          <Blank where={CATALOG_PATH}>
-            No flows yet — a flow is one run across the estate, reconstructed
-            from an integration test or written down by hand. Either way it
-            arrives in <span className="text-ink">flows[]</span>.
-          </Blank>
+          <CapabilityEmpty
+            title={catalog.contexts.length === 0 ? "Connect a project before tracing flows" : "No end-to-end flows yet"}
+            signal="Signals: integration tests, message handlers or authored flows[] catalog fragments."
+            actions={<>
+              <Link className="product-primary" to={catalog.contexts.length === 0 ? paths.settingsProjects() : paths.settingsPipeline()}>{catalog.contexts.length === 0 ? "Connect a project" : "Review extraction"}</Link>
+              {catalog.contexts.length > 0 ? <Link className="tbtn" to={paths.map()}>Open context map</Link> : null}
+            </>}
+          >
+            {catalog.contexts.length === 0
+              ? "Portolan needs a project before it can reconstruct a journey through the architecture."
+              : "A flow is one run across the estate. Portolan can reconstruct it from integration evidence or read an authored flow from the catalog."
+            }
+          </CapabilityEmpty>
         </div>
       ) : rows.length === 0 ? (
         <div className="mt-section">

package/src/pages/GraphPage.tsx

@@ -1,8 +1,9 @@
 import { useDocumentTitle } from "../app/title";
 import { useMemo, useState } from "react";
+import { Link } from "react-router";
 import { catalog } from "../data";
 import { plural } from "../lib/format";
-import { Empty } from "../components/PageHeader";
+import { CapabilityEmpty, Empty } from "../components/PageHeader";
 import {
   bundles,
   edgeCount,
@@ -14,6 +15,7 @@ import { statusColor, statusDash } from "../graph/theme";
 import { DependencyGraphPane } from "../graph/DependencyGraph";
 import type { GraphMode } from "../graph/dependency-layout";
 import type { Status } from "../catalog";
+import { paths } from "../routes";
 
 const STATUSES: { status: Status; note: string }[] = [
   { status: "verified", note: "consumption observed" },
@@ -183,8 +185,8 @@ export function GraphPage() {
       <div className="min-h-0 flex-1">
         {nothing ? (
           <div className="p-gutter">
-            <Empty>
-              {filtered ? (
+            {filtered ? (
+              <Empty>
                 <>
                   no event passes these filters.{" "}
                   <button
@@ -198,10 +200,22 @@ export function GraphPage() {
                     show everything
                   </button>
                 </>
-              ) : (
-                "no events in the catalog yet"
-              )}
-            </Empty>
+              </Empty>
+            ) : (
+              <CapabilityEmpty
+                title={catalog.contexts.length === 0 ? "Connect a project before mapping dependencies" : "No dependency graph yet"}
+                signal="Signals: domain events, message consumers, AsyncAPI channels and integration contracts."
+                actions={<>
+                  <Link className="product-primary" to={paths.settingsProjects()}>{catalog.contexts.length === 0 ? "Connect a project" : "Review project extraction"}</Link>
+                  {catalog.contexts.length > 0 ? <Link className="tbtn" to={paths.map()}>Open context map</Link> : null}
+                </>}
+              >
+                {catalog.contexts.length === 0
+                  ? "Portolan needs at least one project before it can discover events and their consumers."
+                  : "The catalog has components, but no events or consumers to connect yet. Review the selected extractors and the evidence they found."
+                }
+              </CapabilityEmpty>
+            )}
           </div>
         ) : (
           <DependencyGraphPane

package/src/pages/Language.tsx

@@ -13,9 +13,9 @@
 import { useDocumentTitle } from "../app/title";
 import { useMemo, useState } from "react";
 import { Link, useSearchParams } from "react-router";
-import { CATALOG_PATH, catalog, index } from "../data";
+import { catalog, index } from "../data";
 import { allTerms } from "../catalog";
-import { Blank, Empty, SectionTitle } from "../components/PageHeader";
+import { CapabilityEmpty, Empty, SectionTitle } from "../components/PageHeader";
 import { ContextPill } from "../components/primitives";
 import { contextVar } from "../lib/context-color";
 import { plural } from "../lib/format";
@@ -73,13 +73,13 @@ export function Language() {
       <div className="h-full overflow-y-auto p-gutter">
         <h1 className="text-lg font-semibold">Language</h1>
         <div className="mt-section">
-          <Blank where={CATALOG_PATH}>
-            No glossary yet — one file per bounded context, beside its README,
-            saying what each word means inside the boundary and what it does
-            not. They are read from every <span className="text-ink">GLOSSARY.md</span>{" "}
-            the manifest points at and land in{" "}
-            <span className="text-ink">terms[]</span>.
-          </Blank>
+          <CapabilityEmpty
+            title="No bounded-context language yet"
+            signal="Signal: GLOSSARY.md files discovered beside project documentation → terms[]."
+            actions={<Link className="product-primary" to={catalog.contexts.length === 0 ? paths.settingsProjects() : paths.settingsPipeline()}>{catalog.contexts.length === 0 ? "Connect a project" : "Review extraction"}</Link>}
+          >
+            A glossary records what a word means inside one boundary—and what it does not. Portolan combines those files to reveal shared terms and conflicting meanings.
+          </CapabilityEmpty>
         </div>
       </div>
     );

package/src/pages/NotFound.tsx

@@ -1,4 +1,5 @@
-import { Link } from "react-router";
+import { House, Search } from "lucide-react";
+import { Link, useLocation } from "react-router";
 import { useDocumentTitle } from "../app/title";
 
 /**
@@ -34,21 +35,63 @@ export function NotFound({ kind, id }: { kind: string; id?: string }) {
   );
 }
 
-export function NotFoundPage() {
-  useDocumentTitle("Not found");
+function LostExplorer() {
   return (
-    <div className="glow p-gutter">
-      <h1 className="text-lg font-semibold">Not found</h1>
-      <p className="mt-3 text-muted">
-        off the edge of the chart — no route runs through here
-      </p>
-      <SearchHint />
-      <Link
-        to="/"
-        className="mono mt-6 inline-block rounded-control text-accent hover:underline"
-      >
-        ← overview
-      </Link>
+    <div className="not-found-art">
+      <img
+        src={`${import.meta.env.BASE_URL}404-cat-v1.webp`}
+        alt="An explorer cat studying a folded map with a missing route"
+        className="not-found-cat"
+        draggable={false}
+      />
+    </div>
+  );
+}
+
+export function NotFoundPage({ onOpenSearch }: { onOpenSearch: () => void }) {
+  useDocumentTitle("Route not found");
+  const { pathname } = useLocation();
+
+  return (
+    <div className="not-found-page pane">
+      <section className="not-found-state" aria-labelledby="not-found-title">
+        <LostExplorer />
+
+        <div className="not-found-copy">
+          <p className="label text-accent">uncharted route</p>
+          <h1 id="not-found-title" className="mt-2 text-xl font-semibold">
+            Route not found
+          </h1>
+          <p className="mt-3 text-muted">
+            This path runs beyond the current catalog. It may have moved or
+            been renamed since the chart was drawn.
+          </p>
+
+          <div className="not-found-request mt-5">
+            <span className="mono text-faint">requested</span>
+            <code className="mono trunc text-ink" title={pathname}>
+              {pathname}
+            </code>
+          </div>
+
+          <div className="mt-6 flex flex-wrap items-center gap-2">
+            <button
+              type="button"
+              className="product-primary"
+              onClick={onOpenSearch}
+              aria-keyshortcuts="Meta+K Control+K"
+            >
+              <Search size={15} aria-hidden />
+              <span>Search catalog</span>
+              <kbd className="not-found-key">⌘K</kbd>
+            </button>
+            <Link to="/" className="tbtn py-1.5 text-ink">
+              <House size={15} aria-hidden />
+              Back to overview
+            </Link>
+          </div>
+        </div>
+      </section>
     </div>
   );
 }

package/src/pages/Overview.tsx

@@ -105,6 +105,12 @@ export function Overview() {
   const issueCount = issues.length;
   const errorCount = issues.filter((p) => p.severity === "error").length;
 
+  if (catalog.contexts.length === 0) {
+    return (
+      <div className="h-full overflow-y-auto p-gutter"><div className="mx-auto mt-[12vh] max-w-2xl rounded-card border border-accent bg-canvas p-6 shadow-xs"><div className="label mb-2">welcome to Portolan</div><h1 className="text-xl font-semibold text-ink">Turn your first project into an architecture catalog</h1><p className="mt-2 text-muted">Start with one repository. Portolan detects its components and contracts, lets you review the evidence, then generates a navigable map.</p><div className="mt-5 flex flex-wrap gap-2"><Link to={paths.settingsProjects()} className="product-primary">Connect your first project</Link><Link to={paths.settings()} className="tbtn">Open setup guide</Link></div><div className="mono mt-5 border-t border-line pt-4 text-muted">source → context → evidence → preview → map</div></div></div>
+    );
+  }
+
   return (
     <div className="h-full overflow-y-auto p-gutter">
       <div className="flex flex-col items-start gap-1 sm:flex-row sm:items-start sm:gap-x-4">

package/src/pages/Problems.tsx

@@ -14,6 +14,7 @@ import { contextVar } from "../lib/context-color";
 import { absoluteTime, plural, relativeTime } from "../lib/format";
 import { SectionTitle } from "../components/PageHeader";
 import { ProblemRow } from "../components/ProblemRow";
+import { CatEmptyState } from "../components/CatIllustration";
 
 export function Problems() {
   useDocumentTitle("Problems");
@@ -160,14 +161,15 @@ export function Problems() {
 /** The one line the reader wants to see. Nothing else earns the space. */
 function ClearSkies({ checked }: { checked: number }) {
   return (
-    <div className="empty mt-section max-w-table">
+    <CatEmptyState
+      scene="clear"
+      title={checked === 0 ? "Nothing to resolve yet" : "Clear skies"}
+      className="mt-section max-w-prose"
+      meta={<span title={absoluteTime(catalog.generatedAt)}>last checked {relativeTime(catalog.generatedAt)}</span>}
+    >
       {checked === 0
-        ? "Nothing to resolve yet — no service calls another, and no event has a consumer."
-        : `Clear skies — all ${checked} ${plural(checked, "edge")} resolved.`}
-      <span className="ml-2" title={absoluteTime(catalog.generatedAt)}>
-        last checked {relativeTime(catalog.generatedAt)}
-      </span>
-    </div>
+        ? "No service calls another, and no event has a consumer."
+        : `All ${checked} ${plural(checked, "edge")} resolved.`}
+    </CatEmptyState>
   );
 }
-

package/src/pages/RegistryIndex.tsx

@@ -1,8 +1,9 @@
 import { useDocumentTitle } from "../app/title";
 import { useMemo } from "react";
-import { CATALOG_PATH, catalog, index } from "../data";
+import { Link } from "react-router";
+import { catalog, index } from "../data";
 import type { ProtoModule } from "../catalog";
-import { Blank, Empty } from "../components/PageHeader";
+import { CapabilityEmpty, Empty } from "../components/PageHeader";
 import { RowActions } from "../components/RowActions";
 import { DataTable } from "../table/DataTable";
 import type { ColumnSpec } from "../table/types";
@@ -88,12 +89,13 @@ export function RegistryIndex() {
 
       {bare ? (
         <div className="mt-section">
-          <Blank where={CATALOG_PATH}>
-            No schema modules yet — a module is the .proto files an interface
-            was declared in, named and versioned by a registry. They are read
-            from the protos in each repository and land in{" "}
-            <span className="text-ink">modules[]</span>.
-          </Blank>
+          <CapabilityEmpty
+            title="No schema modules discovered yet"
+            signal="Signals: .proto files and registry metadata from BSR or local modules → modules[]."
+            actions={<Link className="product-primary" to={catalog.contexts.length === 0 ? paths.settingsProjects() : paths.settingsPipeline()}>{catalog.contexts.length === 0 ? "Connect a project" : "Review extraction"}</Link>}
+          >
+            Registry modules show where shared contracts are published, pinned and consumed. Review the project’s protobuf and registry extractors to populate this index.
+          </CapabilityEmpty>
         </div>
       ) : (
         <div className="mt-section max-w-table">

package/src/pages/ServicePage.tsx

@@ -284,7 +284,7 @@ export function ServicePage() {
               height={300}
             />
             <div className="mt-section" />
-            <Markdown mermaid>{service.readme}</Markdown>
+            <Markdown mermaid sourceRoot={service.path}>{service.readme}</Markdown>
             {/* What to type to build, test and run it. Under the README
                 rather than in a tab of its own: the list is short, it is the
                 first thing a reader new to the checkout wants, and the README